airec 0.1.0

Experimental Python toolkit for inspecting and reverse engineering the AIREC smart voice recorder over BLE

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:

python -m pip install .

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

python -m pip install airec

The package requires Python 3.12 or 3.13.

Contributor Setup

This repository uses uv for local development:

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

Run tests with:

uv run pytest

Library Example

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 for a compact API guide.

CLI Example

After installation, the airec command is available:

airec scan --timeout 5

Some useful commands:

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, 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:

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/protocol-notes.md

License

MIT. See LICENSE.