Navidrome¶

The short version¶

There are two settings layers:

1. The client app may request an audio format and/or a maximum bitrate.
2. Navidrome can apply a matching per-player transcoding profile that selects or overrides the resulting stream codec and bitrate.

The final truth is in Navidrome’s stream log:

selectedFormat=...
selectedBitrate=...
format=...
bitRate=...

Those fields show what Navidrome actually served.

The roles¶

How a stream is chosen¶

For each play request, Navidrome:

1. Identifies the API client/player.
2. Matches a saved player record when one exists.
3. Determines whether the original file is allowed for that player/request.
4. Applies an applicable per-player transcode profile.
5. Streams either the original media or a transcoded output.

Typical successful transcode sequence:

Found matching player ... type=Arpeggi
Transcode decision: transcode ... targetBitrate=128 targetFormat=opus
Streaming file ... format=opus bitRate=128 transcoding=true

Client requests vs player profiles¶

A Navidrome per-player profile can override the format and bitrate asked for in a legacy Subsonic /rest/stream.view request.

Example: Amperfy can request:

format=mp3&maxBitRate=128

If Navidrome’s matching player profile is configured as Opus / 96 kbps, Navidrome can select and deliver:

selectedFormat=opus
selectedBitrate=96
format=opus
bitRate=96

The format query parameter alone is therefore not the final answer. Always inspect Navidrome’s selected and streamed values.

“Server choose codec” in a client¶

When a client is set to Server choose codec, it may omit format= but still request a maximum bitrate.

For example:

.../stream.view?...&maxBitRate=128

Navidrome can then use the matching player profile to choose the codec. “Server choose codec” means the client permits the server to decide; it does not guarantee that every codec selected by the server will play properly in that particular client.

Your tested clients¶

Arpeggi: confirmed configuration¶

Arpeggi is the clearest working Opus example in your logs.

The request sent to Navidrome is:

format=opus
maxBitRate=128
estimateContentLength=false

Navidrome responds by selecting:

targetFormat=opus
targetBitrate=128
selectedFormat=opus
selectedBitrate=128

The delivered stream is:

format=opus
bitRate=128
sampleRate=48000
channels=2
transcoding=true

Arpeggi then reports successful playback:

positionMs=1000 state=playing

and later:

positionMs=28000 state=paused

The first stream connection was cancelled after a short initial transfer, then a second connection completed with approximately 3.08 MB delivered. This is normal-looking iOS stream setup behavior rather than a server failure.

Recommended Arpeggi cellular profile¶

Arpeggi app: Opus, maximum 128 kbps
Navidrome player profile: Optional; do not override it with another codec unless tested

Because Arpeggi already explicitly asks for Opus / 128 kbps and successfully plays it, the simplest setup is to let Arpeggi control its own streaming request. If you create a Navidrome profile for it, use the same target:

Opus audio, 128 kbps

Do not set a lower server profile unless you intentionally want Navidrome to override Arpeggi’s requested quality.

Recommended practical settings¶

Configure each client according to tested compatibility.

Codec and bitrate¶

• Codec is the compression method: MP3, AAC, Opus, Vorbis, FLAC, etc.
• Bitrate is the amount of data sent each second: 64, 96, 128 kbps, etc.
• A lower bitrate uses less mobile data but can reduce quality.
• Re-encoding an already lossy file such as MP3 is a tradeoff for bandwidth; use it mainly for cellular streaming or constrained networks.

Useful cellular choices:

How to verify a client¶

1. Start playback in the desired app.
2. Watch the Navidrome container log:

docker logs -f navidrome 2>&1 | grep -E "Found matching player|Transcode decision|Streaming file|selectedFormat|selectedBitrate"

1. Find the player Navidrome matched:

Found matching player ... client=... type=...

1. Confirm the actual stream:

Streaming file ... format=... bitRate=... transcoding=true

Do not rely only on:

• The filename extension.
• “OGG” in an app UI—Ogg is a container and can hold Opus or Vorbis.
• The format= URL parameter—Navidrome can override it.
• HTTP status 200 or 206—those confirm delivery, not necessarily successful audio decoding.

Reading common log messages¶

Bottom line¶

For Arpeggi, use Opus at 128 kbps for cellular streaming. It explicitly requests that format, Navidrome serves it unchanged, and the playback reports confirm that it plays successfully.

More generally, use the codec/bitrate each individual client has demonstrated it can play, and verify every change through Navidrome’s selectedFormat, selectedBitrate, format, and bitRate log fields.