Troubleshooting

The app does not start

Every launch writes a log, and a failure before the window opens lands in it. The app prints the path itself under Settings, then You. Read the file directly at:

The file is truncated at every start, so it holds one run and no history. It opens with a version banner; everything after that line is a warning or a crash, and that is what to paste into the bug report. A file with the banner alone means the run was healthy.

Running .\jamstream-app.exe from PowerShell shows nothing: a release build on Windows has no console attached, by design, so the log is the only place the error appears. On macOS and Linux a terminal run also prints to stderr.

A local session server that dies at startup is a different case with its own log; see Playing on the same network.

Latency feels high

Start with the number, not the feel. The headline figure in the session status bar is mouth to ear: the milliseconds from sound entering an interface to the last buffer JamStream hands your sound card, the playout buffer included. What the card holds after that is the one part no figure here can see.

The network is in that figure twice, because your sound crosses to the server and out again to the player hearing it, and your own round trip is charged for both crossings. That is right when the band's connections are alike, and low by the difference when somebody's is worse than yours.

Two players in the same room stand about 3 ms apart per meter of air; a total under 30 ms feels like playing across a large stage, and most people stop noticing under 20 ms.

Check these in order of payoff:

1. Bluetooth. Bluetooth headphones or earbuds add more delay than JamStream's entire network path. Use wired headphones, always. This is the most common cause of "it feels wrong" with a good-looking number.

2. Wifi. Wifi adds jitter, which inflates the jitter buffers. Hover the latency number for the buffer readout, which reads "buffer 3/4 frames": the depth it is holding against the depth it is aiming for, in 2.5 ms frames. If it sits high or climbs, plug in ethernet.

   There are two of them and the number carries both. buffer is your own; server buffer under it is the one the session server holds on your uplink, which your link sets and only the server can see.

   Yours stands in for the buffer under whoever you are listening to, the same way your round trip stands in for theirs.

3. Buffer size. On the Audio tab, under Buffer size, start at the smallest of 120, 240, or 480 frames (2.5, 5, or 10 ms).

   Each step costs three times its own size in the number: the buffer is paid once going in and twice coming out. The hover names both directions, as capture buffer and playout buffer.

   The playout side is not fixed. A machine whose audio keeps coming close to breaking up holds a little more than the size asks for, 2.5 ms at a time and never more than the size again, and gives it back once it is keeping up.

   A line under the choices says how much and why, so the latency you are getting is on screen even when it is not the size you picked. Nothing appears there while the size is all you are paying.

   You are asked to move the size only when that runs out of room. The same line then names the next size up, and says what taking it costs: more latency, and a reopen the band hears as a few hundred milliseconds missing of you. A crackling tag before that means the extra depth is still working on it.

   Add extra depth automatically, under the choices, is how you stop it. Untick it and you get the size you picked and nothing else, on this session and every later one on this computer.

   If the audio still comes close to breaking up with the box unticked, the line says so and points back at it: extra depth is the one fix that costs no reopen. The sizes stay pickable either way, because nothing in the app ever moves the size for you.

4. Sample rate. A direction JamStream's own converter carries costs about 3 ms, and says so with a muted converting tag naming both rates.

   The headline number already includes it and the hover breaks it out per direction. Device problems has the whole ladder.

5. WASAPI mode, on Windows. Exclusive adds about 10 ms, shared 20 to 30. The latency number's hover names which one this session got.

   JamStream asks for exclusive by default. The "Allow exclusive access" setting under Devices turns that off when another app needs the same device, at the shared-mode cost.

   Exclusive mode itself needs "Allow applications to take exclusive control of this device" ticked on the device's Advanced tab in the Sound dialog, for both input and output. Without it the session opens shared instead, and the hover is the only place that says so.

6. Region. If the session's round trip (rtt, on the latency number's hover) is high for you specifically, the server is far from you. The host can pick a fairer region next time; see Hosting a session.

7. Loss. The same hover carries a rate per direction over the last second, so a bad moment clears once it passes. uplink loss is what the band is missing of you; downlink loss is what you are missing of them.

   Both should sit near 0.0%. Above 1% sustained points at the local network: congested wifi, a saturated uplink, a bad cable.

   An uplink loss tag beside the latency number means the band is missing enough of you to hear it. Nothing you hear will tell you, because your monitoring, your meters and the room are all downstream of it. Same fix, from your end.

The band can't keep together

This is a different complaint from a high latency number: everyone sounds right alone, and only together does the tempo sag, worse the further apart the band is.

Each player hears their own instrument immediately and everyone else a full network path away, so the error each one feels is their own mouth to ear number, and no two players carry the same one.

Two fixes, and neither of them moves that number:

• The host turns the click on, in the Metronome panel; each player chooses whether to hear it. The server mixes it into every personal mix, so it reaches everyone on one timeline and the band follows it instead of each other.
• Turn on Hear yourself through the server, on the Audio tab. Your own sound joins the mix, so the gap you hear becomes the difference between two uplinks instead of the whole network path. Needs headphones: through speakers it loops your own signal back into the microphone.

When mouth to ear holds above about 30 ms with somebody else in the room, the Audio tab offers it above that control, once per session. Read the headphone line under it before ticking anything, and leave it off if you are on speakers.

Device problems

Input and output devices are picked on the Audio tab of Settings, under Devices: a Capture picker, a Playback picker, and Rescan beside the heading. The Input level meter above them should move when you play.

The lists come from the platform's audio backend (CoreAudio on macOS, WASAPI on Windows, PipeWire or ALSA on Linux). Each starts with a System default entry that follows the operating system when the default moves, with the concrete devices listed after it.

A change mid-session reopens the stream on the new device without leaving the session.

A stream that stops says so in three places: the device's own reason above the mixer strips, a no audio tag beside the latency number, and both the reason and what the reopen cadence is doing under the pickers.

Sessions run at 48 kHz, and JamStream carries a device at any other rate automatically. A note under the pickers, per direction, names whichever of these it landed on:

On macOS a device another app holds at 44.1 kHz, BlackHole under GarageBand say, is moved to 48 kHz and GarageBand keeps playing, because macOS resamples app output to the device's rate. An app that takes the clock back mid-session gets it: JamStream stops asking and converts instead.

Only the last row costs milliseconds. Any of them goes away if you set the device to 48 kHz yourself:

The one device still refused is a Bluetooth or headset microphone in its hands-free mode: it has no 48 kHz setting anywhere and would sound like a phone call, so use another capture device.

Firewall and NAT

Members need only outbound UDP, so home routers and NAT need no configuration and no port forwarding.

• If joining times out after about 10 seconds, something between you and the server is dropping UDP. Corporate and campus networks sometimes block outbound UDP on unusual ports; a phone hotspot is a quick way to confirm that is the cause.
• Hosting on your own Windows machine is the exception: the first local host raises a Defender Firewall prompt for jamstreamd.exe, and it must be allowed on both Private and Public networks or bandmates on your network hit that same 10 second timeout.

Session ends unexpectedly

Something is still running that should not be

In the app, Stop strays on the Recent sessions card destroys every JamStream-tagged machine in every account this computer holds a key for, and brings the session records back in line with what it found.

It reports three things apart: what it stopped, what it could not stop, and which providers it could not search. A provider with no credentials saved here, or one whose listing failed, was never looked at, which is not the same as finding nothing.

From a terminal:

$ jamstream sweep --dry-run

lists the same machines without destroying them. Run it without --dry-run to destroy them. Either way, a named instance that could not be stopped is still billing; destroy it from the provider's own console and report the bug.