Metadata-Version: 2.4
Name: nothing-headphone-cli
Version: 0.1.0
Summary: Linux CLI and orientation visualizer for Nothing Headphone (1)
Author: Nothing CLI contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/LikelyLucid/nothing-headphone-cli
Project-URL: Documentation, https://github.com/LikelyLucid/nothing-headphone-cli#readme
Project-URL: Issues, https://github.com/LikelyLucid/nothing-headphone-cli/issues
Project-URL: Source, https://github.com/LikelyLucid/nothing-headphone-cli
Keywords: bluetooth,headphones,linux,nothing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pyright>=1.1; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# Nothing Headphone (1) CLI

An unofficial Linux command-line interface and live orientation visualizer for
Nothing Headphone (1). It communicates directly with the headphones over
Bluetooth RFCOMM and has no runtime Python dependencies.

> [!IMPORTANT]
> This project is experimental, is not affiliated with Nothing Technology
> Limited, and has only been tested with Nothing Headphone (1). Settings are
> changed on the connected device at your own risk.

## Requirements

- Linux with Bluetooth socket support
- Python 3.11 or newer
- `bluetoothctl` from BlueZ for automatic device discovery
- A paired and connected Nothing Headphone (1)

## Installation

Install the published package with [`pipx`](https://pipx.pypa.io/), which keeps
command-line applications isolated:

```sh
pipx install nothing-headphone-cli
```

Alternatively, install the current source checkout in a virtual environment:

```sh
python -m venv .venv
. .venv/bin/activate
python -m pip install .
```

This installs two commands: `nothing-cli` and `nothing-visualizer`.

## Settings CLI

The connected headphones are auto-detected through `bluetoothctl`:

```sh
nothing-cli status
nothing-cli anc anc-high
nothing-cli anc transparency
nothing-cli eq balanced
nothing-cli spatial head-tracking
nothing-cli --json status
```

Run `nothing-cli --help` or `nothing-cli COMMAND --help` for the full command
reference. To select a device explicitly, use
`--address AA:BB:CC:DD:EE:FF` or set `NOTHING_HEADPHONE_ADDRESS`.

The `raw-query` command accepts only read-only `0xC000`-class opcodes:

```sh
nothing-cli raw-query 0xc001
```

## Live orientation visualizer

Pair and connect the headphones, then run:

```sh
nothing-visualizer
```

The visualizer opens at <http://127.0.0.1:8765>. Face forward and select
**Recenter forward** (or press `R`) to zero yaw, pitch, and roll. The server
binds to localhost by default. Non-loopback binding is rejected unless
`--allow-remote` is passed; the control endpoints do not authenticate requests,
so remote access is unsafe without an external access-control layer.

An existing calibration is loaded from
`/tmp/nothing-headtrack-calibration.json`. Override it with
`--calibration PATH`, or recenter at any time. The optional fast-yaw workspace
gesture uses `hyprctl` and is therefore specific to Hyprland.

## Troubleshooting

First confirm that BlueZ sees the connected device:

```sh
bluetoothctl devices Connected
```

If it is not listed, pair and connect it with your desktop Bluetooth settings or
`bluetoothctl`. If automatic discovery cannot identify it, pass the address
explicitly:

```sh
nothing-cli --address AA:BB:CC:DD:EE:FF status
```

- **`could not run bluetoothctl`**: install the BlueZ command-line tools.
- **`no connected Nothing Headphone was found`**: connect the headphones or use
  `--address`/`NOTHING_HEADPHONE_ADDRESS`.
- **RFCOMM connection errors**: verify the device remains connected and that the
  current user can create Bluetooth sockets.
- **Visualizer port errors**: choose another local port with `--port PORT`.

When reporting a problem, follow [CONTRIBUTING.md](CONTRIBUTING.md) and remove
Bluetooth addresses from logs. See [SECURITY.md](SECURITY.md) for private
vulnerability reporting guidance.

## Development

```sh
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
ruff check src tests
pyright
pytest
python -m build
python -m twine check dist/*
```

## License

Distributed under the [MIT License](LICENSE).
