Historical recipe — not current setup guidance. Measurements and implementation links below belong to their original workload and revision. Deployment labels and defaults may be obsolete. Use the reviewed performance recipes; browse historical evidence.

AVPlumber · Mixer optimization cookbook

Looped clips keep counting across the wrap

Implementation links are pinned to develop at c20464a5 (2026-10-09). The mixer has changed since; this page was checked against develop at 8fa15c92 on 2026-10-13. Measurements retain their original workload and scope. Watch the current 192-input L4 demo.

Current scope. Continuous loop timestamps remain useful with native-rate input pacing. References below to force_fps describe the historical normalized chain; current mixer file inputs feed realtime directly to the downstream mixer graph.

A looped file used to restart at its first timestamp on every pass, and each wrap cost the source a frame. With loop_continuous_ts, input_rec shifts each new pass by the length of the one before, so timestamps keep rising and a wrap looks like any other frame.

What went wrong at the wrap

File sources from a mixer config loop by default (--input URLs loop with --loop-inputs), and each generated source loops its own clip, 2 s long unless the recipe says otherwise (see Real 1080p inputs). At the end of the file input_rec seeks back to the start, and the next packets carry the file's first timestamps again.

realtime(set_pts) releases each frame when its timestamp is due. The first frame of a new pass looked one loop length overdue, so realtime resynced and released it at once, one frame period early. force_fps then got two frames for one output tick and dropped one: a stutter at every wrap, on every looped file source.

A mixer run with 2 s generated clips, measured when the change was made, showed it: force_fps estimated the input at 60.5 fps, dropped about 0.9 frames per second per source, and every wrap logged three warnings. These numbers come from that run, not from the smoke test below or the 110-source show.

How the shift works

1. Measure each pass. For every packet, input_rec tracks the earliest timestamp and the latest timestamp + duration of the video stream, or of all streams in a file without video. It reads the PTS (the DTS when there is no PTS) and keeps the minimum and maximum over the whole pass, not the last packet's value, so B-frame reordering does not shorten the span. A packet without a duration counts as one frame at the stream's average frame rate, when the file declares one.
2. Add the span at each forward wrap. Both loop points, end of file and stop_ts, go through loopForward(), which adds the finished pass's span to a running loop_offset_ and then seeks to start_ts. A 2 s clip at 25 fps runs from PTS 0 to 1.96 s, and its last frame lasts 0.04 s: span 2 s. Pass 2 is shifted by 2 s, pass 3 by 4 s.
3. Shift every stream by the same offset. Just before a packet leaves input_rec, its PTS and DTS get loop_offset_. Audio gets the video's offset, so audio and video stay in sync.
4. Control stays on file timestamps. stop_ts and seek-at entries compare the file's own timestamps, taken before the shift, and seek targets still resolve in the file. Only forward loops add to the offset; a reverse-playback loop adds nothing.

Where the mixer turns it on

• NVDEC file sources. Both mixer entry points, --input URLs and sources from a config, call build_input(…, continuous_loop=True). input_rec gets loop_continuous_ts only when the source also loops.
• Raw v210 files, and raw NV12/P010 files on the pinned path. _raw_file_packets sets loop_continuous_ts to the source's loop. Rawvideo decode and the patched FFmpeg upload filter preserve the packet timeline, so the shift reaches realtime.
• Raw NV12/P010 files on the direct path, which the setup selects. raw_video_file_cuda does not use input_rec; it takes the same parameter, loop_continuous_ts, set to the source's loop, and counts pictures on across passes.
• Unchanged. The default raw NV12/P010 chain (hwupload) already counts frames with setpts before pacing, so its timestamps were already continuous. The playlist and replay demos seek, so they keep the default. Browser sources and direct raw sources do not use input_rec.

At a glance

• Whatinput_rec gains loop_continuous_ts (default false). Each forward loop adds the previous pass's span to a running offset, and every packet's PTS and DTS carry it. The mixer turns it on for its free-running file loops: NVDEC sources, v210 files and raw NV12/P010 files (through input_rec on the pinned path, through the same parameter of raw_video_file_cuda on direct).
• Why

  A wrap sent the timestamps back one loop length. realtime resynced and released the next pass's first frame a frame early, so each looped source lost a frame and stuttered at every wrap: in a mixer run with 2 s clips, about 0.9 drops/s per source and three log warnings per wrap.

  In normalized helper chains it also helps force_fps.center_phase, which picks its phase on the first frame and again only after a discontinuity it detects. A resync restarts realtime's release times at a new phase, which could leave a source off-center after a wrap. With nothing moving at a wrap, the chosen phase holds across passes.

• Latency0 frames added to program and to command-to-screen latency: no queue, buffer, wait or node. A wrap no longer releases a frame early.
• Side effectsTimestamps of a looped input keep rising instead of repeating the file's range. Only the nodes between input_rec and realtime (demux, the decoder or raw upload node, any decoded filter) see shifted timestamps; realtime(set_pts) restamps every frame onto the host clock, so nothing after it changes. A chain that seeks would aim at file timestamps while its packets carry shifted ones, which is why seeking chains keep the default.
• Cost0 nodes, 0 queues, 0 VRAM, no new thread or lock. Per packet, a few timestamp comparisons and additions. Code: +54/−3 lines in input_rec.cpp and a 141-line smoke test.
• RiskLow. The span follows the video stream, by design: a file whose audio runs a frame longer or shorter than its video still gets the video's offset, so its audio overlaps or leaves a gap at the wrap by that difference. The mixer's file sources route only video. Not for chains that seek.
• Switch it offPass continuous_loop=False at the relevant build_input calls in application.py or cli.py, and set loop_continuous_ts to false in _raw_file_packets for the v210 and pinned chains and in the direct branch of build_raw420_input. On a hand-built graph, leave loop_continuous_ts at its default, false. No runtime switch.

Where in the code

• src/nodes/input_rec.cpp: the flag, loop_offset_ and the current pass's start and end.
• src/nodes/input_rec.cpp: loopForward() adds the pass span to the offset, then seeks to start_ts.
• src/nodes/input_rec.cpp: continueLoopTimeline() measures the pass on the video stream and shifts PTS and DTS.
• src/nodes/input_rec.cpp and 887-890: end of file and stop_ts both loop through loopForward().
• src/nodes/input_rec.cpp: the file PTS is kept for seek-at entries (source), and the shift runs just before the packet is sent.
• src/nodes/input_rec.cpp: the loop_continuous_ts parameter.
• pyplumber/mixer/inputs.py: build_input sets loop_continuous_ts to loop and continuous_loop.
• pyplumber/mixer/inputs.py: _raw_file_packets, the head of the v210 and pinned raw chains.
• pyplumber/mixer/inputs.py and src/nodes/hwaccel/raw_video_file_cuda.cpp (pinned to develop at 8fa15c92): the direct branch of build_raw420_input and the node's own loop_continuous_ts.
• pyplumber/mixer/inputs.py: the default raw chain counts frames with setpts instead.
• pyplumber/mixer/application.py and 729-731: the mixer's two build_input calls pass continuous_loop=True.
• pyplumber/mixer/config.py: config sources loop unless loop is false; demos/mixer/prepare_demo.py: generated clips last 2 s by default.
• tests/smoke_input_loop.py: the default loop repeats its timestamps; continuous mp4 (B-frames + AAC) and rawvideo step one frame period across wraps; paced through realtime(set_pts), the default loop shows early steps and the continuous one stays within 4 ms of the period.

Markdown reference: NODES.md · input_rec documents loop_continuous_ts.

Source links are pinned to the reviewed revision.