dtourolle
fecd6022fe
Master allocated DR-224 and UT-211 while this branch was in flight — the third collision on this work. Everything here moves up by one: DR-224..236 become DR-225..237, UT-211..213 become UT-212..214. UR-079, UR-080 and IR-033 were still free and are unchanged. Mechanical, and matched on each row's own text rather than on its number, so a row cannot be shifted twice or the wrong one caught. Master's DR-224 (the background-audio toggle) and UT-211 are untouched.
417 lines
17 KiB
Rust
417 lines
17 KiB
Rust
//! What stream to play, decided in Rust and handed to a player whole.
|
|
//!
|
|
//! Every player backend — mpv, ExoPlayer, the webview `<video>`/hls.js path —
|
|
//! used to receive a bare URL and re-derive the rest: the frontend decided
|
|
//! "is this HLS?" by looking for `.m3u8` in the string, and nothing anywhere
|
|
//! carried *why* a stream was transcoded or what else the source could have
|
|
//! offered. This module is the replacement contract: one self-describing
|
|
//! [`StreamSelection`] that says what the stream is, how to fetch it, and what
|
|
//! the alternatives were.
|
|
//!
|
|
//! The division of labour it encodes — **Rust decides *what stream*, the player
|
|
//! decides *how to deliver it*** — is the point. A multi-variant playlist handed
|
|
//! to ExoPlayer is still ExoPlayer's to adapt over; Rust never paces bytes.
|
|
//!
|
|
//! TRACES: UR-079 | DR-225
|
|
|
|
use serde::{Deserialize, Serialize};
|
|
|
|
use crate::settings::StreamingQuality;
|
|
|
|
/// How the bytes of a chosen stream are fetched.
|
|
///
|
|
/// This field exists to delete a substring search. The frontend previously
|
|
/// decided which loader to attach by testing `url.contains(".m3u8")`, which is a
|
|
/// domain fact reconstructed in the presentation layer — the same class of leak
|
|
/// as the item-type taxonomy that `check:boundary` guards, and one that breaks
|
|
/// silently the moment a server serves a playlist from a path that does not end
|
|
/// in `.m3u8`, or serves a progressive file from one that does.
|
|
///
|
|
/// Tagged (`{"type":"hls"}`) rather than a bare string so the frontend matches a
|
|
/// discriminant instead of comparing text.
|
|
///
|
|
/// TRACES: UR-079 | DR-225
|
|
#[derive(specta::Type, Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(tag = "type", rename_all = "camelCase")]
|
|
pub enum Transport {
|
|
/// An HLS playlist. The webview attaches hls.js (or Safari's native loader);
|
|
/// ExoPlayer uses its HLS media source.
|
|
Hls,
|
|
/// A single progressive HTTP resource, seekable by byte range.
|
|
Progressive,
|
|
/// A file already on disk — a completed download, or the loopback media
|
|
/// server standing in front of one.
|
|
LocalFile,
|
|
}
|
|
|
|
/// What the server is doing to the source to produce this stream.
|
|
///
|
|
/// Distinct from [`Transport`] because the two are genuinely independent: a
|
|
/// direct-streamed remux and a transcode can both arrive over HLS, and a direct
|
|
/// play can arrive progressively or as a local file. Keeping them apart is what
|
|
/// lets the UI say "this is not costing the server anything" without inferring
|
|
/// it from a URL shape.
|
|
///
|
|
/// TRACES: UR-079 | DR-228
|
|
#[derive(specta::Type, Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(tag = "type", rename_all = "camelCase")]
|
|
pub enum PlaybackKind {
|
|
/// The source file is served untouched. No server CPU, no quality loss.
|
|
DirectPlay,
|
|
/// The container is repackaged but the codecs are copied — cheap, and
|
|
/// visually identical to the source.
|
|
DirectStream,
|
|
/// The server is re-encoding. The only case where a bitrate ceiling can
|
|
/// actually be honoured, and the only one that costs the server real work.
|
|
Transcode,
|
|
}
|
|
|
|
impl PlaybackKind {
|
|
/// Whether the server is spending encoder time on this stream.
|
|
///
|
|
/// The queue carries a `needs_transcoding` flag that predates this enum and
|
|
/// that several seek/reload paths still branch on; this keeps the two from
|
|
/// drifting by making one derive from the other.
|
|
///
|
|
/// TRACES: UR-079 | DR-228
|
|
pub fn needs_transcoding(&self) -> bool {
|
|
matches!(self, PlaybackKind::Transcode)
|
|
}
|
|
}
|
|
|
|
/// The rendition actually negotiated — what the viewer is receiving right now.
|
|
///
|
|
/// `None` on a [`StreamSelection`] when the source is being direct-played as-is:
|
|
/// there is no *chosen* rendition in that case, only the file itself, and
|
|
/// reporting the ceiling that happened to be set would misdescribe it.
|
|
///
|
|
/// TRACES: UR-079 | DR-225, DR-226
|
|
#[derive(specta::Type, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct Rendition {
|
|
/// The rung of the ladder this stream was built against.
|
|
pub quality: StreamingQuality,
|
|
/// Total bits per second the stream may use, when a ceiling applies.
|
|
pub max_bitrate: Option<u64>,
|
|
/// Resolution ceiling, when one applies. `None` preserves the source's.
|
|
pub max_height: Option<u32>,
|
|
/// Video codec the server was asked to produce.
|
|
pub video_codec: Option<String>,
|
|
/// Audio codec the server was asked to produce.
|
|
pub audio_codec: Option<String>,
|
|
}
|
|
|
|
/// One rung of the quality picker, as it applies to *this* media source.
|
|
///
|
|
/// The picker used to be filled from the fixed [`StreamingQuality::ALL`] ladder,
|
|
/// which meant offering "20 Mbps" for a 1.1 Mbps podcast — eight rungs, six of
|
|
/// them indistinguishable from Original. `exceeds_source` is what lets the
|
|
/// frontend render that honestly without knowing anything about bitrates.
|
|
///
|
|
/// TRACES: UR-070, UR-079 | DR-227, DR-121
|
|
#[derive(specta::Type, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct QualityOption {
|
|
pub quality: StreamingQuality,
|
|
/// Human label ("8 Mbps"). Lives in Rust beside the number it describes.
|
|
pub label: String,
|
|
/// Secondary line ("1080p").
|
|
pub detail: String,
|
|
/// True when this rung's ceiling is at or above what the source itself
|
|
/// carries, so selecting it yields the same stream as `Original`.
|
|
///
|
|
/// The frontend renders these differently (or hides them); it does not
|
|
/// decide which they are.
|
|
pub exceeds_source: bool,
|
|
/// The source's own bitrate, when the server reported one. Presentation
|
|
/// only — the picker shows "Original (6.7 Mbps)" rather than a bare word.
|
|
pub source_bitrate: Option<u64>,
|
|
}
|
|
|
|
/// Everything a player backend needs to open a stream, and everything the UI
|
|
/// needs to describe it.
|
|
///
|
|
/// Replaces the bare `String` URL that `get_video_stream_url` used to return.
|
|
///
|
|
/// TRACES: UR-079 | DR-225, DR-227, DR-228
|
|
#[derive(specta::Type, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct StreamSelection {
|
|
/// The URL (or loopback URL) to open.
|
|
pub url: String,
|
|
/// How to fetch it. Replaces the `.m3u8` substring check.
|
|
pub transport: Transport,
|
|
/// What the server is doing to the source to produce it.
|
|
pub playback_kind: PlaybackKind,
|
|
/// The negotiated rendition; `None` when direct-playing the source as-is.
|
|
pub rendition: Option<Rendition>,
|
|
/// What this media source can offer, for the quality picker (DR-227).
|
|
pub available: Vec<QualityOption>,
|
|
/// The media source this selection is for, so a later re-open (quality
|
|
/// change, audio-track switch, transcoded seek) targets the same one.
|
|
pub media_source_id: Option<String>,
|
|
/// The transcode identity the server keyed this job by, when there is one.
|
|
pub play_session_id: Option<String>,
|
|
/// Whether the server is spending encoder time on this stream.
|
|
///
|
|
/// Derived from [`playback_kind`](Self::playback_kind) rather than left for
|
|
/// the frontend to compute: "which kinds count as transcoding" is a domain
|
|
/// rule, and a direct *stream* is a remux that must not be counted. The
|
|
/// queue's long-standing `needs_transcoding` flag and the seek strategy both
|
|
/// read this, so there is one answer rather than three.
|
|
///
|
|
/// TRACES: UR-079 | DR-225, DR-228
|
|
pub needs_transcoding: bool,
|
|
}
|
|
|
|
impl StreamSelection {
|
|
/// A selection for a file already on disk.
|
|
///
|
|
/// A downloaded file is a direct play by definition — the bytes are the
|
|
/// source's — and offering a quality ladder over it would be a lie, since
|
|
/// nothing about a local file can be re-negotiated.
|
|
///
|
|
/// TRACES: UR-071, UR-079 | DR-225
|
|
pub fn local_file(url: impl Into<String>) -> Self {
|
|
Self {
|
|
url: url.into(),
|
|
transport: Transport::LocalFile,
|
|
playback_kind: PlaybackKind::DirectPlay,
|
|
rendition: None,
|
|
available: Vec::new(),
|
|
media_source_id: None,
|
|
play_session_id: None,
|
|
needs_transcoding: false,
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Build the quality ladder as it applies to a source of a known bitrate.
|
|
///
|
|
/// Every rung is returned — the picker stays a fixed, predictable list rather
|
|
/// than one that changes length per item — but each is marked with whether it
|
|
/// would actually constrain *this* source. A rung whose ceiling is at or above
|
|
/// the source bitrate produces the same bytes as `Original`, so presenting it as
|
|
/// a distinct choice is noise.
|
|
///
|
|
/// `source_bitrate` is `None` when the server did not report one (it is absent
|
|
/// for some containers — the sampled library has `avi` files with no bitrate at
|
|
/// all). In that case nothing can be judged redundant and every rung is offered,
|
|
/// which is the safe direction: the viewer keeps every choice they had before.
|
|
///
|
|
/// TRACES: UR-070, UR-079 | DR-227, DR-121 | UT-212
|
|
pub fn quality_options_for_source(source_bitrate: Option<u64>) -> Vec<QualityOption> {
|
|
StreamingQuality::ALL
|
|
.iter()
|
|
.map(|quality| QualityOption {
|
|
quality: *quality,
|
|
label: quality.label().to_string(),
|
|
detail: quality.detail().to_string(),
|
|
exceeds_source: match (quality.max_bitrate(), source_bitrate) {
|
|
// `Original` is the source; it never "exceeds" it.
|
|
(None, _) => false,
|
|
// Nothing known about the source — judge nothing redundant.
|
|
(Some(_), None) => false,
|
|
(Some(cap), Some(source)) => cap >= source,
|
|
},
|
|
source_bitrate,
|
|
})
|
|
.collect()
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
/// The tag the frontend matches on has to be exactly what it expects, and
|
|
/// it is a *string in TypeScript* — nothing but a test keeps the two in step.
|
|
///
|
|
/// TRACES: UR-079 | DR-225 | UT-212
|
|
#[test]
|
|
fn test_transport_serialises_with_the_tag_the_frontend_matches() {
|
|
let cases = [
|
|
(Transport::Hls, r#"{"type":"hls"}"#),
|
|
(Transport::Progressive, r#"{"type":"progressive"}"#),
|
|
(Transport::LocalFile, r#"{"type":"localFile"}"#),
|
|
];
|
|
for (transport, expected) in cases {
|
|
let json = serde_json::to_string(&transport).expect("serialises");
|
|
assert_eq!(json, expected, "wire shape of {transport:?}");
|
|
let back: Transport = serde_json::from_str(&json).expect("round-trips");
|
|
assert_eq!(back, transport);
|
|
}
|
|
}
|
|
|
|
/// TRACES: UR-079 | DR-228 | UT-212
|
|
#[test]
|
|
fn test_playback_kind_serialises_with_the_tag_the_frontend_matches() {
|
|
let cases = [
|
|
(PlaybackKind::DirectPlay, r#"{"type":"directPlay"}"#),
|
|
(PlaybackKind::DirectStream, r#"{"type":"directStream"}"#),
|
|
(PlaybackKind::Transcode, r#"{"type":"transcode"}"#),
|
|
];
|
|
for (kind, expected) in cases {
|
|
let json = serde_json::to_string(&kind).expect("serialises");
|
|
assert_eq!(json, expected, "wire shape of {kind:?}");
|
|
let back: PlaybackKind = serde_json::from_str(&json).expect("round-trips");
|
|
assert_eq!(back, kind);
|
|
}
|
|
}
|
|
|
|
/// Only a transcode costs the server encoder time. A direct *stream* is a
|
|
/// remux — cheap, and not what `needs_transcoding` has ever meant.
|
|
///
|
|
/// TRACES: UR-079 | DR-228 | UT-212
|
|
#[test]
|
|
fn test_only_transcode_counts_as_transcoding() {
|
|
assert!(PlaybackKind::Transcode.needs_transcoding());
|
|
assert!(!PlaybackKind::DirectStream.needs_transcoding());
|
|
assert!(!PlaybackKind::DirectPlay.needs_transcoding());
|
|
}
|
|
|
|
/// A local file is a direct play over a local transport, with no ladder:
|
|
/// nothing about a file on disk can be re-negotiated.
|
|
///
|
|
/// TRACES: UR-071, UR-079 | DR-225 | UT-212
|
|
#[test]
|
|
fn test_local_file_selection_offers_no_ladder() {
|
|
let selection = StreamSelection::local_file("http://127.0.0.1:9000/media/x.mkv");
|
|
assert_eq!(selection.transport, Transport::LocalFile);
|
|
assert_eq!(selection.playback_kind, PlaybackKind::DirectPlay);
|
|
assert!(selection.rendition.is_none());
|
|
assert!(selection.available.is_empty());
|
|
assert!(!selection.needs_transcoding);
|
|
}
|
|
|
|
/// The camelCase rule applies to nested struct fields too, and
|
|
/// `playbackKind` is the one the frontend branches on.
|
|
///
|
|
/// TRACES: UR-079 | DR-225 | UT-212
|
|
#[test]
|
|
fn test_stream_selection_fields_are_camel_case_on_the_wire() {
|
|
let selection = StreamSelection {
|
|
url: "https://example/master.m3u8".to_string(),
|
|
transport: Transport::Hls,
|
|
playback_kind: PlaybackKind::Transcode,
|
|
rendition: Some(Rendition {
|
|
quality: StreamingQuality::Mbps8,
|
|
max_bitrate: Some(8_000_000),
|
|
max_height: Some(1080),
|
|
video_codec: Some("h264".to_string()),
|
|
audio_codec: Some("aac".to_string()),
|
|
}),
|
|
available: Vec::new(),
|
|
media_source_id: Some("src-1".to_string()),
|
|
play_session_id: Some("sess-1".to_string()),
|
|
needs_transcoding: true,
|
|
};
|
|
let json = serde_json::to_string(&selection).expect("serialises");
|
|
assert!(
|
|
json.contains(r#""playbackKind":{"type":"transcode"}"#),
|
|
"{json}"
|
|
);
|
|
assert!(json.contains(r#""transport":{"type":"hls"}"#), "{json}");
|
|
assert!(json.contains(r#""mediaSourceId":"src-1""#), "{json}");
|
|
assert!(json.contains(r#""playSessionId":"sess-1""#), "{json}");
|
|
assert!(json.contains(r#""maxBitrate":8000000"#), "{json}");
|
|
assert!(json.contains(r#""maxHeight":1080"#), "{json}");
|
|
assert!(json.contains(r#""needsTranscoding":true"#), "{json}");
|
|
}
|
|
|
|
/// The measured library has 1.1 Mbps sources in it. Offering those a choice
|
|
/// of 20, 10, 8, 4 and 2 Mbps is offering five ways to spell "Original".
|
|
///
|
|
/// TRACES: UR-070, UR-079 | DR-227, DR-121 | UT-212
|
|
#[test]
|
|
fn test_rungs_above_the_source_bitrate_are_marked_redundant() {
|
|
let options = quality_options_for_source(Some(1_122_137));
|
|
let redundant: Vec<_> = options
|
|
.iter()
|
|
.filter(|o| o.exceeds_source)
|
|
.map(|o| o.quality)
|
|
.collect();
|
|
assert_eq!(
|
|
redundant,
|
|
vec![
|
|
StreamingQuality::Mbps20,
|
|
StreamingQuality::Mbps10,
|
|
StreamingQuality::Mbps8,
|
|
StreamingQuality::Mbps4,
|
|
StreamingQuality::Mbps2,
|
|
],
|
|
"every rung at or above a 1.12 Mbps source is the source"
|
|
);
|
|
|
|
// The rungs that genuinely constrain it are not marked.
|
|
let constraining: Vec<_> = options
|
|
.iter()
|
|
.filter(|o| !o.exceeds_source)
|
|
.map(|o| o.quality)
|
|
.collect();
|
|
assert_eq!(
|
|
constraining,
|
|
vec![
|
|
StreamingQuality::Original,
|
|
StreamingQuality::Mbps1,
|
|
StreamingQuality::Kbps720,
|
|
]
|
|
);
|
|
}
|
|
|
|
/// `Original` is the source, so it is never "above" it — not even for a
|
|
/// source whose bitrate is unknown or zero.
|
|
///
|
|
/// TRACES: UR-070, UR-079 | DR-227 | UT-212
|
|
#[test]
|
|
fn test_original_is_never_marked_as_exceeding_the_source() {
|
|
for bitrate in [None, Some(0), Some(1), Some(50_000_000)] {
|
|
let options = quality_options_for_source(bitrate);
|
|
let original = options
|
|
.iter()
|
|
.find(|o| o.quality == StreamingQuality::Original)
|
|
.expect("Original is always offered");
|
|
assert!(!original.exceeds_source, "bitrate {bitrate:?}");
|
|
}
|
|
}
|
|
|
|
/// An `avi` with no reported bitrate must not lose the picker. Judging
|
|
/// nothing redundant is the safe direction — the viewer keeps every choice.
|
|
///
|
|
/// TRACES: UR-070, UR-079 | DR-227 | UT-212
|
|
#[test]
|
|
fn test_an_unknown_source_bitrate_keeps_every_rung_offered() {
|
|
let options = quality_options_for_source(None);
|
|
assert_eq!(options.len(), StreamingQuality::ALL.len());
|
|
assert!(
|
|
options.iter().all(|o| !o.exceeds_source),
|
|
"nothing can be judged redundant without a source bitrate"
|
|
);
|
|
assert!(options.iter().all(|o| o.source_bitrate.is_none()));
|
|
}
|
|
|
|
/// A 4K remux constrains at every rung — the ladder is fully meaningful.
|
|
///
|
|
/// TRACES: UR-070, UR-079 | DR-227 | UT-212
|
|
#[test]
|
|
fn test_a_source_above_the_ladder_marks_nothing_redundant() {
|
|
let options = quality_options_for_source(Some(40_000_000));
|
|
assert!(options.iter().all(|o| !o.exceeds_source));
|
|
}
|
|
|
|
/// The picker's text comes from Rust, beside the numbers it describes, so a
|
|
/// relabelled rung cannot drift out of step with what it does.
|
|
///
|
|
/// TRACES: UR-070, UR-079 | DR-227 | UT-212
|
|
#[test]
|
|
fn test_options_carry_the_ladder_labels() {
|
|
let options = quality_options_for_source(Some(6_652_961));
|
|
assert_eq!(options.len(), StreamingQuality::ALL.len());
|
|
for (option, quality) in options.iter().zip(StreamingQuality::ALL) {
|
|
assert_eq!(option.quality, quality);
|
|
assert_eq!(option.label, quality.label());
|
|
assert_eq!(option.detail, quality.detail());
|
|
assert_eq!(option.source_bitrate, Some(6_652_961));
|
|
}
|
|
}
|
|
}
|