Metadata-Version: 2.4
Name: airec
Version: 0.1.0
Summary: Experimental Python toolkit for inspecting and reverse engineering the AIREC smart voice recorder over BLE
Author-email: Max Kerr <maxrmk@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: airec,ble,bluetooth,reverse-engineering,voice-recorder
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.12
Requires-Dist: bleak<0.23,>=0.22
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == 'dev'
Description-Content-Type: text/markdown

# airec

`airec` is an experimental Python toolkit for inspecting and reverse engineering the AIREC smart voice recorder over Bluetooth Low Energy.

It ships as both:

- a Python library for scripted inspection and offline analysis
- a command-line tool for scanning, probing, tracing, and decoding captured device data

The current scope is practical device investigation, not a polished general-purpose BLE SDK.

## Installation

Install from a source checkout or built distribution with `pip`:

```bash
python -m pip install .
```

Once published to a package index, the install command will be:

```bash
python -m pip install airec
```

The package requires Python 3.12 or 3.13.

## Contributor Setup

This repository uses `uv` for local development:

```bash
uv venv --python 3.12
uv sync --extra dev
```

Run tests with:

```bash
uv run pytest
```

## Library Example

```python
import asyncio

from airec import AirecClient, scan_devices


async def main() -> None:
    devices = await scan_devices(timeout=5.0)
    if not devices:
        return

    client = AirecClient(devices[0].address)
    profile = await client.inspect()
    print(profile.to_dict())
    await client.disconnect()


asyncio.run(main())
```

The documented public API includes:

- `airec.AirecClient`
- `airec.scan_devices`
- exported protocol models such as `DeviceProfile`, `RecordingInfo`, and `StorageStatus`
- offline helpers such as `analyze_session_log`, `decode_session_log`, `decode_recording_download`, and `summarize_pklg_trace`
- `airec.__version__`

See [docs/library-usage.md](docs/library-usage.md) for a compact API guide.

## CLI Example

After installation, the `airec` command is available:

```bash
airec scan --timeout 5
```

Some useful commands:

```bash
airec inspect <device-address>
airec survey <device-address> --duration 10
airec list-recordings <device-address>
airec download-recording <device-address> <recording-id>
airec trace-pklg documentation/BluetoothTraceFile.pklg
airec analyze artifacts/sessions/session.jsonl
```

Many commands support `--json` for structured output.

## Platform Notes

- Live BLE operations use [`bleak`](https://github.com/hbldh/bleak), so behavior depends on the local platform BLE stack.
- macOS, Linux, and Windows are supported at the dependency level, but most device validation in this repository has been done on macOS.
- Several CLI commands intentionally exercise undocumented device behavior. Treat them as investigative tools, not stable end-user workflows.

## macOS Bluetooth Permission

On macOS, CoreBluetooth can abort the interpreter if the host `Python.app` bundle does not declare `NSBluetoothAlwaysUsageDescription` in its `Info.plist`. This often affects Homebrew Python framework builds.

Before the first live BLE command, patch the active interpreter bundle:

```bash
python3.12 scripts/patch_macos_python_app_bundle.py
```

Then rerun the BLE command and macOS should prompt for Bluetooth access instead of crashing.

## Project Status

This package is experimental and currently optimized for:

- discovering device services and characteristics
- capturing structured session logs from live experiments
- inspecting PacketLogger `.pklg` traces
- reconstructing and decoding archived recording payloads

The README focuses on the supported package surface. Deeper reverse-engineering notes live separately:

- [docs/library-usage.md](docs/library-usage.md)
- [docs/protocol-notes.md](docs/protocol-notes.md)

## License

MIT. See [LICENSE](LICENSE).
