ikarishinji/jbl-nsdk-volume-controller repository overview

⁠JBL nSDK Volume Controller

A small, touch-friendly LAN volume controller for JBL active speakers using the StreamUnlimited nSDK API. It changes player:volume by exactly one unit per tap, avoiding the large jumps produced by some phone volume buttons.

⁠Why

On some JBL active speakers, iOS AirPlay and Bluetooth volume buttons can move the speaker by several nSDK units at once. The enlarged system slider can select intermediate values, but its useful low-volume area is very small. This controller provides large − and + buttons that always request a one-unit change.

The app runs entirely on the local network. It has no cloud dependency and does not modify speaker firmware.

⁠Compatibility

• JBL 4305P: tested on firmware 0.101.2139.0x4f26c1f.
• JBL 4329P: designed for compatibility with the same JBL/StreamUnlimited nSDK volume interface; not yet verified on physical hardware.
• Other nSDK-based speakers may work if they expose the same /api/getData and /api/setData endpoints.

⁠Features

• Exact nSDK player:volume +1 / -1 control
• Current volume display with silent background synchronization
• Mute and unmute
• Adjustable safety ceiling from 1 to 100, stored in the browser
• Mobile-friendly interface
• Self-contained Python service with no third-party runtime packages
• Multi-platform Docker image for linux/amd64 and linux/arm64
• Suitable for OpenWrt, NAS devices, Raspberry Pi, mini PCs and home servers

⁠Quick start

Replace SPEAKER_HOSTNAME_OR_ADDRESS with the speaker hostname or LAN address:

docker run -d \
  --name jbl-volume \
  --restart unless-stopped \
  -e JBL_HOST=SPEAKER_HOSTNAME_OR_ADDRESS \
  -p 8765:8765 \
  ikarishinji/jbl-nsdk-volume-controller:latest

Open:

http://DOCKER_HOSTNAME_OR_ADDRESS:8765/

⁠Docker Compose

services:
  jbl-volume:
    image: ikarishinji/jbl-nsdk-volume-controller:latest
    container_name: jbl-volume
    restart: unless-stopped
    environment:
      JBL_HOST: SPEAKER_HOSTNAME_OR_ADDRESS
    ports:
      - "8765:8765"

Start it with docker compose up -d.

⁠ARM64

Docker automatically selects the correct image for x86_64/amd64 or aarch64/arm64:

docker pull ikarishinji/jbl-nsdk-volume-controller:latest

docker run -d \
  --name jbl-volume \
  --restart unless-stopped \
  -e JBL_HOST=SPEAKER_HOSTNAME_OR_ADDRESS \
  -p 8765:8765 \
  ikarishinji/jbl-nsdk-volume-controller:latest

If the page is not reachable from the LAN, allow inbound TCP port 8765 from the LAN zone in the OpenWrt firewall.

⁠Configuration

JBL_IP remains accepted as a backwards-compatible alias for JBL_HOST.

⁠How it works

The backend reads player:volume. For each tap it writes the current value plus or minus one through nSDK /api/setData, then reads the state back. Mute uses settings:/mediaPlayer/mute.

The controller does not change hostlink/maxVolume, volumeMap, softvolEnabled, ALSA routing or firmware.

⁠Limitations

• This improves control density but does not create new DSP gain levels inside the speaker.
• Phone hardware volume buttons are not intercepted; use the web controls.
• There is no authentication. Run it only on a trusted home LAN and do not expose port 8765 to the internet.
• Compatibility depends on the speaker exposing the expected nSDK nodes.

⁠Local development

Python 3.11 or newer is sufficient:

JBL_HOST=SPEAKER_HOSTNAME_OR_ADDRESS python server.py

Then open http://localhost:8765/.

⁠Build

docker build -t jbl-nsdk-volume-controller .

Multi-platform build:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t YOUR_DOCKERHUB_USER/jbl-nsdk-volume-controller:latest \
  --push .

⁠License

MIT