#Troubleshooting

Quick fixes for the most common problems. If a stream misbehaves in a way that isn't listed, record the session and read the numbers before changing settings: see Performance.

#Audio and video drift apart

You asked for a bigger grid than your machine can encode and send in time, so video falls behind the audio clock. Lower --cols until playback keeps up. Grids beyond the automatic caps need --no-resolution-limit, which makes this more likely, not less.

#FileNotFoundError for ffmpeg or ffprobe

FFmpeg isn't on your PATH (common on Windows). Install it with winget install ffmpeg, or drop ffmpeg.exe and ffprobe.exe next to stream_server.py.

#Black SDK output

Serve the modules over HTTP(S), not from file://, and copy the whole src/ folder: asciline-player.js imports live-session.js. See the SDK reference.

#DCT is not active (pixels arrive as raw)

DCT needs three things at once: pixel mode, a file source, and a client that advertises support. Older clients, including older asciline-player releases from npm, fall back to raw. Check the SDK's init event (pixelCodec) and the server's [DCT] log line to see what was actually negotiated. See Live streaming.

#Rust video works but audio doesn't

Check which FFmpeg runtime the Rust module recorded and the server's /audio diagnostics. The Rust build and the audio path use FFmpeg separately.

#BUF: 0 in the stats

On its own this doesn't prove a stall. Just-in-time delivery shows an empty buffer while playing perfectly. Correlate server delivery, decode backlog, rendered frame count and clock progress before drawing conclusions.

#YouTube or URL playback fails or hangs

Install the extra (pip install ".[ytdlp]"); it is not needed for local files. The first play of a URL downloads and normalizes it, which takes a while. If a download that used to work now fails, yt-dlp itself is probably out of date: upgrade it.

#Disk fills up with cached downloads

Lower --cache-limit (MB) to cap the LRU cache in videos/.

#Studio output is large or slow to compile

The browser Studio encoder only emits RAW, ZLIB and DELTA and is meant for short clips. For long or size-sensitive videos use compiler.py. See Static player.

#The terminal player garbles mid-video

Don't resize the terminal while ascii_video_player2.py is running.

#Still stuck?

Ask in the Discord or open an issue with your command line, OS, and the output of --debug.