cuframes-composer/docs/LESSONS-audio-mixing-attempts.md

LESSONS: попытки добавить audio mixing в cuframes-composer

Контекст: cuframes-composer (gx/cuframes-composer) композирует 4 cuframes-источника в grid через CUDA kernels + NVENC H.264, публикует в mediamtx cfc-grid path (только video). Параллельно cuda-grid-pipeline (legacy монолитный ffmpeg) публикует live с video + AAC audio — но месяц подёргивается из-за известного audio chain блокирует video бага (см. memory feedback).

Цель Phase 7 — реализовать audio mixing в composer'е/около него чтобы:

1. Получить стабильное video + audio в одном потоке
2. Retire pipeline'а полностью

Статус 2026-06-03: не достигнута, откатано на parallel mode.

---

Что в итоге работает (текущее prod-состояние)

rtsp://...:554/live     — pipeline, H264+AAC, подёргивается уже месяц (audio mix bag)
rtsp://...:554/cfc-grid — composer, H264 only, стабильное video
rtsp://...:554/live-audio — cuda-grid-audio, AAC only

TV/VLC рекомендуется использовать cfc-grid для video и (опционально) синхронизировать live-audio параллельно на стороне reader'а до того как Phase 7 будет завершён.

---

Хронология попыток и почему каждая не сработала

Попытка 1: cfc-grid-ffmpeg mux — raw H.264 в pipe + RTSP audio → -c copy

ffmpeg -f h264 -i /pipe/grid.h264 -i rtsp://.../live-audio -c copy -map 0:v -map 1:a -f rtsp ...

Проблема: Raw H.264 в pipe не имеет PTS/DTS на container-уровне. ffmpeg синтезирует через -r 25 или wallclock, audio RTSP с правильными RTP timestamps, interleave broken. Mediamtx drops video либо audio. Symptoms: 4 fps video (от 25), Could not write header, audio с перебоями.

Что я пробовал из костылей (всё бесплодно):

• -use_wallclock_as_timestamps 1 на video — ломает audio DTS (Non-monotonic DTS)
• -fflags +genpts+igndts+discardcorrupt — не помогает
• -thread_queue_size 32/1024 — без эффекта
• -muxdelay 0 -max_delay 0 — без эффекта
• -flush_packets 1 — без эффекта

Попытка 2: decode→re-encode через NVDEC+NVENC в cfc-grid-ffmpeg

-hwaccel cuda -i /pipe/grid.h264 -c:v h264_nvenc -intra_refresh 1 -no-scenecut 1 ...

Проблема: Broken pipe на RTSP output mediamtx. Также double-encode на GPU удваивает NVENC sessions (на Pascal GTX 1050 это уже впритык, на 5090 OK но всё равно лишний overhead).

Попытка 3: композитор пишет mpegts container нативно (Phase 7 core)

Архитектура: composer через libavformat → mpegts container → Unix socket в mediamtx. Решает PTS/DTS на container-уровне + bypass'ит весь split-process pipe→ffmpeg-mux pipeline.

Реализация в src/writer.c, src/audio.c, mediamtx MTX_PATHS_CFCGRID_SOURCE=unix+mpegts:///....

3.1: PPS error non-existing PPS 0 referenced

Причина: libavformat mpegts muxer автоматически инсёртит h264_mp4toannexb bitstream-фильтр, который ожидает AVCC формат (length-prefix NAL units). NVENC выдаёт Annex-B (start codes). При попытке "конвертации" парсер ломается.

Дополнительная инъекция SPS/PPS через NV_ENC_PIC_FLAG_OUTPUT_SPSPPS per-frame (который я добавил пытаясь решить late-joiner проблему) усугубляет — двойная инжекция создаёт мусор для парсера.

Fix: убрать NV_ENC_PIC_FLAG_OUTPUT_SPSPPS per-frame. Оставить только repeatSPSPPS=1 в init. NVENC сам ставит SPS/PPS перед каждым началом intra refresh cycle.

См. также OBS Studio issue #7338 — intra refresh + NVENC + mpegts = известно сломанная пара в индустрии.

3.2: 12 секунд latency

Причины (сложение):

• -analyzeduration 30000000 -probesize 50000000 в ffmpeg-mux input — 30 секунд hard cap на пробинг (libavformat ждёт байт пока поймёт codec). Для intra refresh stream без IDR ffmpeg вынужден ждать первого refresh cycle.
• av_interleaved_write_frame буферизует пакеты до max_interleave_delta (default 10 секунд).
• Default AVIO write buffer 256KB — на 6 Mbps это ~350ms.
• Named pipe (FIFO) + stdio buffers по 64KB ещё ~100ms.
• Сложение ≈ 12+ секунд.

Fix частично: AVFMT_FLAG_FLUSH_PACKETS, max_interleave_delta=200000 (200ms), уменьшение thread_queue, -flush_packets 1. Не убирает все источники — глубже композитор/AVIO buffering остаётся.

3.3: omit_video_pes_length не существует во flags

Fix: убрать. Достаточно +resend_headers+pat_pmt_at_frames.

3.4: mediamtx env-var MTX_PATHS_CFC_GRID_SOURCE не разбирается

mediamtx env parser использует _ как разделитель между <NAME> и <FIELD>. Дефис в path name (cfc-grid) ломает pattern → mediamtx думает что path называется cfc а grid_source это что-то другое.

Fix: переименовать path в cfcgrid (без дефиса) либо использовать YAML config file.

3.5: mediamtx закрывает Unix socket — read unix: i/o timeout

Default mediamtx ReadTimeout = 10 секунд. Composer пишет с burst'ами (8 audio packets после каждого video frame), AVIO buffers накапливаются, socket I/O slow → mediamtx видит idle > 10s → disconnect → composer reconnects → cycle.

Partial fix: MTX_READTIMEOUT=30s + MTX_WRITETIMEOUT=30s в mediamtx env. Помогает не полностью.

3.6: malloc_consolidate(): unaligned fastbin chunk detected (heap corruption)

Причина 1 (исправлена): av_packet_alloc() + manual av_malloc(pkt->data) + затем av_interleaved_write_frame — конфликт ownership. av_interleaved_write_frame берёт ownership packet'а через AVBufferRef, но у меня data была вне buffer ref → libav освобождает невалидно.

Fix: использовать av_new_packet(pkt, size) — создаёт proper AVBufferRef, дальше memcpy в pkt->data.

Причина 2 (исправлена): SPSC ring buffer в audio.c — когда полный, producer (audio thread) free'ил oldest данные и двигал tail index. Но tail — это домен consumer'а (main thread). Concurrent modification → use-after-free → heap corruption.

Fix: при full ring drop newest (free(new_pkt.data); return -1), не трогать tail.

3.7: Non-monotonic DTS для audio packets

Audio packets часто приходят пачкой через TCP (несколько AAC frames в одном recv). Если назначать PTS как wallclock_now - start, все они получат идентичный timestamp → non monotonic DTS от mpegts muxer.

Fix: monotonic PTS на основе накопленных samples'ов. AAC-LC = 1024 samples/frame. pts_ns = total_samples * 1_000_000_000 / sample_rate. total_samples += 1024 per frame.

3.8: Video PTS skew с audio PTS

Video PTS было через wall-clock relative to start. Audio PTS — через accumulated samples. Разные clock sources → постепенный drift со временем.

Fix: video PTS тоже через monotonic counter: pts = frame_idx * duration_per_frame, где duration_per_frame = 1/fps в time_base. Это даёт точный 25 fps tempo без skew от composer thread jitter.

---

Что осталось нерешённым (для будущей попытки)

Даже после всех вышеперечисленных фиксов финальный результат был:

• Звук с затыками
• Видео тормозит
• Периодические разрывы соединения VLC

Гипотезы про оставшийся источник проблем:

1. mediamtx + Unix socket backpressure под burst write'ами. Когда composer пишет video frame + drain 8 audio packets подряд за один tick, mediamtx видит burst, reader queue заполняется, reader падает. См. MTX_WRITEQUEUESIZE=256 (default слишком мал для burst'ов, увеличение влияет на latency).

2. AVIO буфер vs AVFMT_FLAG_FLUSH_PACKETS. Возможно flag flush'ит после каждого packet'а, но av_interleaved_write_frame ставит packets в interleave queue ДО flush'а. Net эффект: queue до 200ms (max_interleave_delta), потом burst flush.

3. mpegts muxer не низколатентный по дизайну. Mediamtx внутренне распаковывает PES → собирает свои RTSP track'и → пакетизирует в RTP. Каждый шаг добавляет buffering. Возможно правильный путь — gortsplib встроенный RTSP publisher (паттерн C из RESEARCH-audio-mixing-low-latency.md), который не использует mpegts контейнер вовсе.

4. Composer audio drain timing. Я drain'ю до 8 packets после каждого video frame. При 43 audio packets/sec (44.1k/1024) и 25 video frames/sec получается 43/25 = 1.72 packets/frame в среднем. С drain'ом до 8 — большинство фреймов drain'ит 1-2 packets, но при катэппинге очереди (после coмposer pause или audio source jitter) batch'ит до 8. Это может вызывать interleave irregular.

   Альтернатива — drain до 1 packet'а за раз, но N раз пер video tick. Либо drain по wall-clock cadence audio (через timerfd на 23.22ms tick).

5. Pre-allocation/post-allocation race. Mediamtx ожидает PAT/PMT для path ready'нения. Мой first frame отправляет PAT/PMT (через pat_pmt_at_frames flag), но возможно несколько initial frames проходят без PAT/PMT и mediamtx считает их корруптом.

---

Что писать ДО следующей попытки

Benchmark-driven research — недостаточно теоретического плана. Нужно:

1. Замерить реальную latency на каждой stage'и через timestamps в логах:

   • composer compose_compose finish → encode_frame begin
   • encode_frame begin → on_bitstream callback
   • on_bitstream → av_interleaved_write_frame return
   • av_interleaved_write_frame → byte appears в /run/mediamtx/sock (через strace -e write)
   • mediamtx receives → mediamtx sends RTP packet (через mediamtx logs DEBUG)
   • RTP packet → VLC decoder ready (VLC verbose logs)

2. Сравнить с baseline'ом — cuda-grid-pipeline даёт <1s end-to-end пока audio mix не block'ает video. Что у него отличается архитектурно? Один процесс, один muxer, один encoder thread. Mediamtx видит rtsp publisher вместо unix-mpegts publisher.

3. **Изучить mediamtx mpeg-ts internals — unix+mpegts:// source насколько хорошо протестирован? Возможно есть known bag'и. Issue tracker bluenviron/mediamtx.

4. Альтернативные пути:

   • rtsp publisher через gortsplib — gortsplib это Go библиотека, не C, но можно попробовать обвязку через CGo или standalone Go-процесс с TCP control от composer'а.
   • RTP-based publisher напрямую — собрать H.264 NAL units в RTP packets (RFC 6184), AAC в mpeg4-generic RTP (RFC 3640), отправлять на mediamtx RTSP ANNOUNCE/RECORD session. Самый low-latency но самый много кода (~1500 строк).

5. Подумать про прочный workaround: 2 отдельных RTSP path'а (cfc-grid для video, live-audio для audio) и client-side sync. VLC/mpv поддерживают это через --audio-file=rtsp://...:554/live-audio. Это не "правильный" монолитный поток но зато стабильное.

---

Список созданных файлов (остались в репо для будущей доработки)

include/cuframes_composer/writer.h    — public API: cfc_writer_create/write/write_audio/close
                                          Поддерживает h264 raw + mpegts container
                                          formats. Audio stream опциональный.
include/cuframes_composer/audio.h     — public API: cfc_audio_create/get_codec_params/
                                          drain/destroy. SPSC ring buffer architecture.

src/writer.c                          — backend impl. Lessons: av_new_packet vs av_malloc,
                                          AVFMT_FLAG_FLUSH_PACKETS, max_interleave_delta=200000,
                                          monotonic video PTS на frame_idx,
                                          monotonic audio PTS на total_samples
src/audio.c                           — audio thread, lock-free SPSC ring (drop newest при
                                          full), RTSP open с low-latency options
                                          (nobuffer+flush_packets, probesize=32768,
                                          analyzeduration=0), AAC parameters discovery

src/nvenc.c                           — encoder. Lesson: убрать NV_ENC_PIC_FLAG_OUTPUT_SPSPPS
                                          per-frame, оставить только repeatSPSPPS=1

examples/grid_record.c                — --audio-source=rtsp://... + --format=mpegts options
docs/RESEARCH-audio-mixing-low-latency.md — research-doc с industry patterns и
                                          recommended approach (паттерн B = mpegts через
                                          Unix socket)
docs/LESSONS-audio-mixing-attempts.md — этот файл

gx/cuframes-composer:0.6 image содержит всё необходимое (libavformat-dev в builder, libavformat58 в runtime). Audio mixing включается через --format=mpegts --audio-source=rtsp://...:8554/live-audio в command'е.

Для возвращения к Phase 7 деплою — раскомментировать MTX_PATHS_CFCGRID_SOURCE в mediamtx env vars + изменить cfc-grid command в compose. См. git history localhost-infra для exact diff'ов.

---

TL;DR для следующего раза

1. Не повторять добавление NV_ENC_PIC_FLAG_OUTPUT_SPSPPS per-frame — двойная инжекция SPS/PPS ломает downstream parsers.
2. Не повторять SPSC ring где producer трогает tail (consumer's side) — heap corruption. Drop newest, не oldest.
3. Не использовать av_packet_alloc + manual av_malloc(data) с av_interleaved_write_frame — нужен av_new_packet для AVBufferRef.
4. Не использовать wall-clock PTS если есть монотонный счётчик (frame_idx / total_samples) — гарантирует sync video/audio.
5. Audio packets приходят пачками через TCP — нельзя назначать PTS = wallclock(now).
6. mpegts muxer + h264_mp4toannexb BSF — несовместим с intra refresh без careful setup. См. OBS issue #7338.
7. mediamtx env-var path names не могут иметь - (parser ломается на _ boundary).
8. Default mediamtx ReadTimeout=10s — слишком короткий для composer'а с burst write'ами.
9. analyzeduration/probesize в ffmpeg input — главные виновники multi-second startup latency, не реальной streaming latency.
10. Не пытаться "наobum experiments" с flag'ами — каждое изменение должно быть основано на measurement или цитате из доков. Иначе rabbit hole'у нет конца.

Главный insight: даже идеально сделанный mpegts через Unix socket путь имеет inherent buffering, который не убрать без переходом на native RTP/RTSP publisher. Возможно, правильный финальный путь — gortsplib (паттерн C из research-doc), но это +1500 строк кода.