vantadsp 0.2.1

VantaDSP: safe JBL Portable Bluetooth protocol, EQ, CLI, and TUI toolkit

VantaDSP

VantaDSP is a safety-first Python toolkit and monochrome terminal interface for inspecting and controlling EQ on speakers supported by JBL Portable. It was built from static analysis of JBL Portable 6.9.12 and hardware validation, without modifying the original APK.

Independent interoperability project. Not affiliated with or endorsed by JBL or Harman. All trademarks belong to their owners. Do not commit or redistribute APK or firmware files with this repository.

Highlights

• Clean monochrome TUI with device discovery, model-aware EQ, live status, packet preview, and activity logs
• BLE scan, advertisement/manufacturer-data inspection, and full GATT service discovery
• Harman/JBL BLE GATT and Bluetooth Classic SPP transports
• Legacy simple, advanced-level, and parametric EQ codecs
• Protocol 4 0E02 parametric and Grip-style 0E7F quantized EQ codecs
• PID-based automatic protocol routing across 37 catalogued models
• 24 curated sound profiles mapped to each model's band layout and quantization
• Read-only multi-generation probing, raw packet capture/decoding, and expert packet transmission
• Dry-run by default, explicit write interlocks, target hashing, and JSONL audit logs

Install

Install the latest release from PyPI:

python -m pip install vantadsp

To install from a cloned repository instead:

python -m pip install .

For development, use an editable installation with the QA toolchain:

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Launch the TUI:

vantatui

The interface provides DEVICE, EQUALIZER, and ACTIVITY workspaces, plus a detailed SYSTEM / DEVICE / PROTOCOL / SAFETY status strip. Writes remain locked until enabled and confirmed with the exact text APPLY. Audit records store a hash of the target instead of its Bluetooth address.

Runtime configuration and audit files are stored under %LOCALAPPDATA%\vantadsp\ on Windows. Bluetooth must be enabled, and Windows must permit desktop apps to use Bluetooth and location. For SPP, pair the speaker first and locate its outgoing COM port in Device Manager.

Safe workflow

Close JBL Portable on nearby phones first so it does not compete for the connection.

vantactl scan
vantactl services --address DEVICE_FROM_SCAN
vantactl probe --address DEVICE_FROM_SCAN
vantactl models
vantactl model --pid 20e3

Known default BLE values extracted from the APK:

service  65786365-6C70-6F69-6E74-2E636F6D0000
RX       65786365-6C70-6F69-6E74-2E636F6D0001
TX       65786365-6C70-6F69-6E74-2E636F6D0002

Some products derive a service UUID from PID/MID. Use services to discover it, then pass --service, --rx, and --tx overrides if necessary.

Read legacy and Protocol 4 EQ without changing the speaker:

vantactl read-simple --address DEVICE
vantactl read-advanced --address DEVICE
vantactl read-p4 --address DEVICE

EQ and sound profiles

Mutating commands only print the encoded TX packet unless --apply is supplied. The recommended path is PID-aware routing:

vantactl set-auto --pid 20e3 5 3 -2.5 -3 -2 -.5 1
vantactl set-profile --pid 20e3 bass
vantactl set-profile --pid 20e3 clear --address DEVICE --apply
vantactl profiles

set-auto chooses legacy simple, advanced-level, legacy parametric, Protocol 4 0E02, or Grip-style 0E7F from the APK-derived model profile. It refuses products for which the APK does not declare EQ support.

Included profiles cover Flat, Balanced, Bass Heavy, Deep Bass, Punch Bass, Warm, Loudness, Crystal Clear, Bright, Detail Monitor, Vocal, Podcast, Acoustic, Rock, Metal, Hip-Hop, EDM, Pop, Jazz, Classical, Cinema, Gaming, Outdoor, and Night. See Sound profiles.

Examples for direct codec control:

# Legacy 3-band signed levels
vantactl set-simple 4 1 -1

# Legacy advanced signed levels
vantactl set-advanced 3 2 1 0 -1 -2 -3

# Legacy parametric bands: type,frequency,gain,q
vantactl set-parametric `
  "low-shelf,125,3,0.7" `
  "peaking,250,2,2" `
  "peaking,500,0,2" `
  "peaking,1000,-1,2" `
  "peaking,2000,0,2" `
  "peaking,4000,1,2" `
  "high-shelf,8000,2,0.7"

# Charge 6 custom-band order: 125, 250, 500, 1k, 2k, 4k, 8kHz
vantactl set-charge6 5 3 -2.5 -3 -2 -.5 1

Filter types are low-shelf, peaking, high-shelf, low-pass, and high-pass. Charge 6 custom band 1 supports -9..+6 dB with asymmetric negative quantization; bands 2-7 support -6..+6 dB in 0.5 dB steps, matching the APK UI mapping.

Capture, decode, and expert mode

vantactl capture --address DEVICE --seconds 15 --output capture.jsonl
vantactl decode "AA9800"
vantactl raw "AA6C00"
vantactl raw "AA6C00" --address DEVICE --apply --i-understand-raw

Raw transmission requires both --apply and --i-understand-raw. No OTA, authentication bypass, factory reset, destructive command, or amplifier/limiter overclock path is implemented.

For Bluetooth Classic SPP, use an outgoing COM port instead of a BLE address:

vantactl raw "AA6C00" --port COM7 --apply --i-understand-raw

Python API

from vantadsp.protocol import build_simple_eq_set, parse_legacy_frame

packet = build_simple_eq_set(bass=4, mid=1, treble=-1)
frame = parse_legacy_frame(packet)
print(packet.hex(), frame)

Protocol builders perform no Bluetooth I/O, so they are deterministic and reusable. Real transmission is isolated in vantadsp.transport; applications should retain an explicit safety confirmation layer.

Documentation

• Protocol reference
• Supported models
• Hardware-confirmed Charge 6 profile
• Sound profiles
• Security and QA audit

Quality assurance

ruff format --check .
ruff check .
mypy src/vantadsp
pytest
bandit -q -c pyproject.toml -r src/vantadsp
pip-audit .
python -m build
twine check dist/*

GitHub Actions tests Windows and Linux on Python 3.10 and 3.12 with coverage, linting, typing, security, and package validation. APK/XAPK files, decompilation output, captures, local configuration, and audit logs are excluded from version control.