chunk #4: doc refreshes — jvm.md Pairer section + python.md transport rewrite - #43
Merged
Conversation
Adds the missing `## Pipeline pairing (org.tstrans.pipeline.Pairer)` section to docs/languages/jvm.md, covering concept, Java example (try-with-resources + instanceof pattern matching), variant/exception model, and Gotchas block. Matches the page's house style. Also removes the now-fulfilled "a documented … Pairer section on this page" clause from the roadmap follow-ups bullet, and adds a "How to pair video with KLV metadata" line to the "You will learn" block.
The python.md guide was frozen pre-Phase-5: it claimed "file I/O only / live SRT unavailable", cited ~582 pytest, and carried a v2/v3 roadmap. The live transports (srt/rtp/udp/tcp/rist), RTSP client+server, SRT auto-reconnect, and tstrans.pipeline.Pairer all shipped and were undocumented. Add jvm.md-scale sections for SRT (raw + MuxSender/DemuxReceiver + Managed*), RTP (raw + convenience + RTSP client + RTSP server), UDP/TCP/RIST, the experimental HLS publisher (flagged not-in-wheels), and Pipeline pairing. Update the intro framing, Status box (~1149 pytest), "Where this binding differs", and Roadmap. Every signature verified against the .pyi stubs / PyO3 #[pymethods] (the rtp convenience shells have no cancel_handle in the Rust source — the .pyi was stale). Also fix a stale add_klv() call in First send.
There was a problem hiding this comment.
Pull request overview
Docs-only polish/parity refresh for the language guides, bringing JVM and Python documentation up to date with the shipped transport + pipeline surfaces and adding missing Pairer usage guidance.
Changes:
docs/languages/jvm.md: adds a new “Pipeline pairing (org.tstrans.pipeline.Pairer)" section and removes a stale roadmap bullet.docs/languages/python.md: rewrites the page to document the current Python surface (SRT/RTP/RTSP/UDP/TCP/RIST, HLS caveats, Pairer), and fixes/updates examples to match current signatures.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/languages/python.md | Major refresh: updated status/intro, added transport sections and tstrans.pipeline.Pairer guide, and corrected examples/caveats. |
| docs/languages/jvm.md | Adds org.tstrans.pipeline.Pairer usage section and removes an outdated roadmap item. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| pairer = Pairer(video_pid, klv_pid, cfg) | ||
| outputs = pairer.feed(ts_bytes) | ||
| outputs += pairer.flush() # drain end-of-stream (no-op in Realtime) |
|
|
||
| try (Pairer pairer = new Pairer(videoPid, klvPid, cfg)) { | ||
| List<PairerOutput> outs = new ArrayList<>(pairer.feed(tsBytes)); | ||
| outs.addAll(pairer.flush()); // drain end-of-stream (no-op in Realtime) |
Comment on lines
+1397
to
+1398
| - **`flush()` is load-bearing only in Buffered mode.** In Realtime mode it is a | ||
| no-op. Always call it at end-of-stream when using Buffered mode. |
aklofas
added a commit
that referenced
this pull request
Jun 15, 2026
…ltime) The PairingDemuxer/Pairer flush() rustdoc, the JVM nFlush rustdoc, and the Pairer.java Javadoc all described flush() as "a no-op in Realtime mode". That is inaccurate: the core flush() drains unused KLV history and emits trailing UnpairedKlv in BOTH modes (e.g. metadata that arrived after the last video access unit) — only the buffered-video drain is Buffered-specific. Proven by the `flush_realtime_drains_unused_klv_history` test (nearest.rs). Skipping flush() in Realtime can silently drop tail metadata. Corrects the four source-comment sites (the user-facing docs/languages/ jvm.md + python.md pages were already fixed in chunk #4 / PR #43). Also de-qualifies the Swift per-language idiom row that implied flush is Buffered-only. Docstring-only — no API/behavior change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Final unit of the polish/parity pass — docs-only (two
docs/languages/pages; no code/CI-surface change).jvm.md — add the
pipeline.Pairersectiondocs/languages/jvm.mdhad no usage section fororg.tstrans.pipeline.Pairer(only an intro + a stale roadmap mention). Added a## Pipeline pairing (org.tstrans.pipeline.Pairer)section after the RTSP server section, matching the## Codec parsing/## SRT conveniencehouse style: the concept (correlates video + KLV by PTS, wrappingtst_pipeline::ext::pairing::PairingDemuxer), a grounded try-with-resources example adapted from the realPairerTest, thePairerOutputvariants + value types, and a gotchas list. Also removed a now-fully-stale roadmap bullet ("data push-family parity follow-ups") — bothMountHandle.pushData/pushDataToandManagedMuxSender.pushData/pushDataToshipped in chunk #2 (PR #40), and the Pairer-section clause it also carried is now done.python.md — macro-stale rewrite
docs/languages/python.mdwas frozen pre-Phase-5: it claimed "file I/O only / live SRT unavailable", cited "~582 pytest", and carried a v2/v3 roadmap — while the entire live transport surface shipped and was undocumented. Rewritten to a full jvm.md-scale guide:.pyi/PyO3-verified hello-worlds.import tstrans.hls→ImportErrorfrom a wheel; only--features hlssource builds expose it); RIST is excluded from the Windows wheel.Two source-grounded catches during the rewrite: applied SOURCE-WINS where
rtp.pyilistscancel_handle()on the RTPMuxSender/DemuxReceiverbut the PyO3 source doesn't expose it (documented per source, matching jvm.md); and fixed a genuinely-broken existing example (add_klv(0x102)→ the realadd_klv(pid, stream_type, *, carries_pts)signature).Verification
Docs-only diff (exactly
jvm.md+python.md) — code rails (clippy/tests/public-api/#[non_exhaustive]/fuzz) are no-ops. Ran:cargo fmt --all --check; the fullscripts/checkbash-ratchet sweep (incl.doc-abi-and-st1910-currency,publisher-class-mirror, and the forbidden-name scrub guard) — all pass; forbidden-token grep clean; fences balanced; anchor links resolve. Each task went through an independent doc-accuracy review against the PyO3/Java source.