termuxlib 📱🐍

A lightweight, type-annotated Python wrapper around Termux API command‑line utilities on Android.

termuxlib exposes native termux-api utilities as structured static Python classes, allowing you to control hardware, sensors, notifications, SMS, text-to-speech, camera, GPS, and Wi-Fi in few lines of code.

---

Prerequisites

Your Android environment must have Termux and its API package configured:

1. Install the main Termux application.
2. Install the Termux:API addon.
3. Inside Termux, run:

   pkg update && pkg install termux-api python -y
   

4. Ensure the Termux:API app has the required Android permissions (Location, SMS, Contacts, Camera, etc.).

---

Installation

To use termuxlib locally, clone this repository or copy the termuxlib directory into your project root.

You can also install the package in editable mode:

pip install -e .

---

Core Concept

All wrappers are defined as @staticmethod functions inside organized modules.

Complex data outputs (such as battery status, location, sensor and network lists) are returned as raw JSON strings directly from the underlying Termux CLI. This keeps the library lightweight and lets you parse outputs as needed:

import json
from termuxlib import device

battery = json.loads(device.battery_status())
print(f"Battery level: {battery['percentage']}% ({battery['status']})")

---

Quick Start

from termuxlib import send_notification, device, tts, clipboard

send_notification("System Alert", "Process started.")
print(device.battery_status())
tts.speak("Termux lib loaded.")
clipboard.copy("Hello from Python!")

---

API Reference

1. Notifications

send_notification(title: str, content: str) -> None

Triggers a native Android notification.

from termuxlib import send_notification
send_notification("Title", "Body message")

---

2. Device & Sensors (device)

Provides access to hardware information and physical sensors.

Method	Return	Description
battery_status()	str (JSON)	Retrieves battery state (level, health, temperature).
location_gps()	str (JSON)	Gets GPS location (latitude, longitude, altitude).
sensor_list()	str (JSON)	Lists all available hardware sensors.
sensor_read(target: str)	str	Reads a single value from the specified sensor (e.g., light).
get_fingerprint()	str (JSON)	Prompts biometric fingerprint authentication.

from termuxlib import device

light_level = device.sensor_read("light")
print(device.get_fingerprint())

---

3. Text-to-Speech (tts)

Synthesizes spoken text using the Android TTS engine.

Method	Return	Description
engine_list()	str	Lists available TTS engines on the device.
speak(text: str)	None	Speaks the given text aloud.

from termuxlib import tts

print(tts.engine_list())
tts.speak("Action completed successfully.")

---

4. SMS (sms)

Manages text messages and contact databases.

Method	Return	Description
contact_list()	str (JSON)	Lists system contacts.
send(phone_number: str, msg: str)	None	Sends an SMS message to a phone number.
sms_list()	str (JSON)	Retrieves received SMS messages.

from termuxlib import sms

sms.send("+1234567890", "Automated system update.")

---

5. Telephony (telephony)

Accesses cellular connection details and handles outbound calls.

Method	Return	Description
info()	str (JSON)	Retrieves network and carrier information.
makecall(phone_number: str)	None	Places an outbound call to the target number.

from termuxlib import telephony

print(telephony.info())
telephony.makecall("+1234567890")

---

6. Wi-Fi (wifi)

Monitors current network states and scans nearby networks.

Method	Return	Description
info()	str (JSON)	Retrieves details of the active Wi-Fi connection.
scan_networks()	str (JSON)	Performs a scan and returns visible Wi-Fi networks.

from termuxlib import wifi

print(wifi.info())

---

7. Clipboard (clipboard)

Manipulates the Android system clipboard.

Method	Return	Description
copy(text: str)	None	Copies text into the clipboard.
read_clipboard()	str	Reads current clipboard content.

from termuxlib import clipboard

clipboard.copy("Target payload")
print(clipboard.read_clipboard())

---

8. Camera & Flashlight (camera)

Manages photo capture and toggles the hardware torch.

Method	Return	Description
info()	str (JSON)	Retrieves device camera specifications.
take_photo(output_file: str, camera: str)	None	Captures a photo with the "front" or "back" camera.
torch(state: bool)	None	Sets the flashlight state (True for on, False for off).

from termuxlib import camera

camera.torch(True)
camera.take_photo("/sdcard/Pictures/capture.jpg", camera="back")
camera.torch(False)

---

Error Handling

All standard execution errors from Termux calls propagate as standard subprocess.CalledProcessError.

import subprocess
from termuxlib import camera

try:
    camera.take_photo("/sdcard/image.jpg", camera="back")
except subprocess.CalledProcessError as e:
    print(f"Termux command failed: {e}")

---

Examples

To view end-to-end operational automation scripts (such as a battery alert, SMS responder, or a GPS locator):

👉 Go to Examples Documentation (docs/EXAMPLES.md)

---

License

This project is licensed under the terms of the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for details.