NetMD Uploader

The NetMD Uploader isolates ATRAC conversion and exclusive NetMD USB writes from Home Assistant Core. It has two supported deployment methods:

1. Home Assistant App (HAOS): install this repository as an App repository. The existing netmd_uploader/Dockerfile and config.yaml are retained for this purpose.
2. Standalone Docker service (Home Assistant Container, Portainer, Docker Compose): run the same uploader API as a separate container. This is the supported route when Home Assistant has no Supervisor/App store, including Home Assistant Container on Debian, OpenMediaVault, a Raspberry Pi, or a conventional amd64 Linux server.

The standalone Dockerfile is architecture-neutral and builds natively on linux/amd64 and linux/arm64; no platform: setting is required.

Standalone Docker / Portainer Compose

Use this mode if Home Assistant itself runs as a Docker container. The NetMD device must be physically attached to the Docker host.

1. Clone this repository on the Docker host and change to netmd_uploader.
2. Copy .env.example to .env and set NETMD_MEDIA_DIR to an absolute host directory for the audio files.
3. Mount that same host directory in the Home Assistant service at /media/netmd (read-only is sufficient).
4. Deploy compose.yaml with docker compose up -d --build, or create a Portainer Stack from its contents.

The supplied Compose file passes /dev/bus/usb to the uploader and keeps the HTTP API private on the Docker network named netmd; do not add a ports: entry unless a separate, protected client genuinely needs API access.

For Home Assistant to reach the uploader, connect its service to the external network netmd and configure the HA-NetMD integration with http://netmd-uploader:8099 as the uploader URL. (Existing HAOS entries retain their current local-netmd-uploader.local.hass.io default.) An existing Compose deployment can do this as follows:

services:
  homeassistant:
    # ...existing configuration...
    volumes:
      - /srv/netmd-media:/media/netmd:ro
    # Required by the current HA-NetMD integration for playback controls and
    # metadata. The uploader uses the same device only during a transfer.
    devices:
      - /dev/bus/usb:/dev/bus/usb:rwm
    networks:
      - default
      - netmd

networks:
  netmd:
    external: true
    name: netmd

The source path passed to the uploader is deliberately restricted to /media/netmd. Therefore the shared directory must be mounted at exactly that path in both containers. Files below /config/www are not supported because that location is intended for public web assets.

USB permissions on Linux

Ensure the Docker host permits access to the connected Sony NetMD device (a udev rule may be necessary). Replug the device after changing udev rules. The Compose devices mapping grants the uploader read/write access without using privileged: true.

Important limitation of the current HA integration

The uploader handles uploads only. The current HA-NetMD integration still uses direct USB access for player controls and metadata. In a Home Assistant Container deployment, it therefore also needs the devices mapping shown above. The uploader temporarily takes exclusive control during a transfer; do not run another USB client against the recorder while an upload is active.