diff --git a/CHANGELOG.md b/CHANGELOG.md index de81e33f..31352007 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,20 @@ out first, whether or not it breaks a compile. ## [Unreleased] +### Added + +- **The scan records each track's music video** + ([RFC-029](docs/rfcs/RFC-029-track-music-video.md) decision 3), in a new + table, `track_clip`. The clip is the video named like the track, case + ignored, beside it or in a `Clips` folder beside it, or the track's own + `.mp4` when it holds a moving picture; several candidates are taken in the + order `mp4`, `m4v`, `mov`, `webm`, `mkv`, each confirmed by its content. + The rule is the desktop's, and a test holds the server's answer to + `waveflow_core::scanner::clips::find_clip` over every case it + distinguishes. Nothing a client sees changes yet; serving the clip is the + next step. A link is dropped only where the scan could see its clip go, + so a `Clips` folder that cannot be read keeps its links. + ### Fixed - **A music video beside its song is no longer a second track** diff --git a/docs/rfcs/RFC-029-track-music-video.md b/docs/rfcs/RFC-029-track-music-video.md index 75fd3b35..e8b15bf0 100644 --- a/docs/rfcs/RFC-029-track-music-video.md +++ b/docs/rfcs/RFC-029-track-music-video.md @@ -3,7 +3,9 @@ - **Status**: Proposed - **Implemented by**: [#449](https://github.com/InstaZDLL/waveflow-server/pull/449) (the core pin), [#450](https://github.com/InstaZDLL/waveflow-server/pull/450) - (decision 4, with decision 3's `Clips` scope); the rest is not yet. The + (decision 4, with decision 3's `Clips` scope), + [#451](https://github.com/InstaZDLL/waveflow-server/pull/451) (decisions 2 + and 3, the link the scan records); the rest is not yet. The *Status* field above never flips in this project; this line is the one that says what is running. - **Date**: 2026-11-14 diff --git a/migrations-v2/20261114000000_track_clip.sql b/migrations-v2/20261114000000_track_clip.sql new file mode 100644 index 00000000..7103726c --- /dev/null +++ b/migrations-v2/20261114000000_track_clip.sql @@ -0,0 +1,25 @@ +-- A track's music video, as the scan found it on the disk. RFC-029 decision 3. +-- +-- The disk is the authority: no route writes here, only the scan's link pass, +-- which records what the desktop's rule (`waveflow_core::scanner::clips`) +-- answers for each track it walked. A table rather than a column on `track` +-- because an incremental scan skips an unchanged audio file without writing +-- its row, and a clip added beside it must still be recorded. +-- +-- `library_id` is the track's, read in the writing transaction, never +-- computed from the clip's path, as `track_canvas` does it. +-- +-- `byte_size` and `modified_at` let the next incremental scan take an +-- unchanged candidate as confirmed without opening it, the trade RFC-018 +-- already makes for audio; a full scan reads it again. +CREATE TABLE track_clip ( + track_id TEXT PRIMARY KEY NOT NULL REFERENCES track(id) ON DELETE CASCADE, + library_id TEXT NOT NULL REFERENCES library(id) ON DELETE CASCADE, + relative_path TEXT NOT NULL, + format TEXT NOT NULL CHECK (format IN ('mp4', 'm4v', 'mov', 'webm', 'mkv')), + origin TEXT NOT NULL CHECK (origin IN ('sibling', 'clips_dir', 'itself')), + byte_size INTEGER NOT NULL CHECK (byte_size >= 0), + modified_at INTEGER NOT NULL +) STRICT; + +CREATE INDEX track_clip_by_library ON track_clip(library_id); diff --git a/src/library/scanner/clips/mod.rs b/src/library/scanner/clips/mod.rs new file mode 100644 index 00000000..636423e7 --- /dev/null +++ b/src/library/scanner/clips/mod.rs @@ -0,0 +1,303 @@ +//! A track's music video, found by the desktop's rule over what the walk saw +//! (RFC-029 decisions 2 and 3), and the pass that records it. +//! +//! The rule is `waveflow_core::scanner::clips::find_clip`: a video named like +//! the track, case ignored, beside it, else in a `Clips` folder beside it, +//! else the track's own file when it holds a moving picture; several +//! candidates in `VIDEO_EXTENSIONS` order, each confirmed by its content, and +//! no neighbour offered to a track that is itself inside a `Clips` folder. +//! `find_clip` lists a folder for every track it is asked about, so the scan +//! matches names in memory over what the walk already listed and reads the +//! disk only to confirm a candidate. This copy is held to `find_clip` by a +//! test over a fixture tree, which is what fails first if the core's rule +//! changes. + +use std::{ + collections::{HashMap, HashSet}, + ffi::OsStr, + io::Read, + path::{Path, PathBuf}, +}; + +use uuid::Uuid; +use waveflow_core::scanner::clips::{has_video_track, is_clips_dir_name, VIDEO_EXTENSIONS}; + +use super::discovery::Walked; +use super::extract::stamp; +use super::ScanManager; +use crate::storage::catalog::{TrackClip, TrackClipFacts}; + +#[cfg(test)] +mod tests; + +/// The containers whose content `has_video_track` can confirm. The core +/// keeps its own list private; an `.mp4` or a `.mov` may hold audio alone. +const ISO_BMFF_EXTENSIONS: &[&str] = &["mp4", "m4v", "mov"]; + +/// What every WebM and Matroska file starts with. That is all the core checks +/// for these two, so a WebM holding audio alone passes, here as on the +/// desktop (RFC-029 decision 2). +const EBML_MAGIC: [u8; 4] = [0x1a, 0x45, 0xdf, 0xa3]; + +/// A catalogue name split into its folder (`""` at the root) and file name. +fn split(name: &str) -> (&str, &str) { + name.rsplit_once('/').unwrap_or(("", name)) +} + +fn extension(file: &str) -> Option { + Path::new(file) + .extension() + .and_then(OsStr::to_str) + .map(str::to_ascii_lowercase) +} + +/// The name a track and its clip share, as the core compares it. +fn stem(file: &str) -> Option { + Path::new(file) + .file_stem() + .and_then(OsStr::to_str) + .map(str::to_lowercase) +} + +fn rank(name: &str) -> usize { + let extension = extension(split(name).1).unwrap_or_default(); + VIDEO_EXTENSIONS + .iter() + .position(|known| *known == extension) + .unwrap_or(VIDEO_EXTENSIONS.len()) +} + +/// One video a track may have, in the order the rule asks them. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) struct Candidate<'a> { + pub(super) path: &'a Path, + pub(super) name: &'a str, + pub(super) origin: &'static str, +} + +/// The videos one walk saw, indexed by folder and name. +pub(super) struct Videos<'a> { + list: &'a [(PathBuf, String)], + /// `(folder, stem)` → indices into `list`, in `VIDEO_EXTENSIONS` order. + named: HashMap<(&'a str, String), Vec>, + /// A folder → its `Clips` folder, the first by name when the disk holds + /// two spellings of it. + clips_dirs: HashMap<&'a str, &'a str>, +} + +impl<'a> Videos<'a> { + pub(super) fn new(list: &'a [(PathBuf, String)]) -> Self { + let mut named: HashMap<(&str, String), Vec> = HashMap::new(); + let mut clips_dirs: HashMap<&str, &str> = HashMap::new(); + for (index, (_, name)) in list.iter().enumerate() { + let (folder, file) = split(name); + if let Some(stem) = stem(file) { + named.entry((folder, stem)).or_default().push(index); + } + let (parent, last) = split(folder); + if !folder.is_empty() && is_clips_dir_name(OsStr::new(last)) { + let known = clips_dirs.entry(parent).or_insert(folder); + *known = (*known).min(folder); + } + } + for indices in named.values_mut() { + indices.sort_by(|&left, &right| { + (rank(&list[left].1), &list[left].1).cmp(&(rank(&list[right].1), &list[right].1)) + }); + } + Self { + list, + named, + clips_dirs, + } + } + + /// Every video the rule would try for `track`, in the order it tries them: + /// beside it, then in its `Clips` folder, then the track's own file. `path` + /// is the track's file, read only for the last. + pub(super) fn candidates<'t>(&'t self, track: &'t str, path: &'t Path) -> Vec> { + let (folder, file) = split(track); + let Some(stem) = stem(file) else { + return Vec::new(); + }; + let mut found = Vec::new(); + let in_clips_dir = !folder.is_empty() && is_clips_dir_name(OsStr::new(split(folder).1)); + if !in_clips_dir { + let mut named = |folder: &'t str, origin: &'static str| { + for &index in self + .named + .get(&(folder, stem.clone())) + .map(Vec::as_slice) + .unwrap_or_default() + { + let (path, name) = &self.list[index]; + if name != track { + found.push(Candidate { path, name, origin }); + } + } + }; + named(folder, "sibling"); + if let Some(clips) = self.clips_dirs.get(folder) { + named(clips, "clips_dir"); + } + } + if extension(file).is_some_and(|own| ISO_BMFF_EXTENSIONS.contains(&own.as_str())) { + found.push(Candidate { + path, + name: track, + origin: "itself", + }); + } + found + } +} + +/// Whether a file holds what its container promises: a moving picture for +/// the ISO-BMFF ones, the EBML header for the others. A file too short to +/// hold the header holds no video; a file that cannot be read is an error, +/// which is not the same answer. +fn holds_video(path: &Path, format: &str) -> std::io::Result { + let mut file = std::fs::File::open(path)?; + let answer = if ISO_BMFF_EXTENSIONS.contains(&format) { + has_video_track(&mut file) + } else { + let mut head = [0u8; 4]; + file.read_exact(&mut head).map(|()| head == EBML_MAGIC) + }; + match answer { + // Truncated: what the file holds was read, and it is not a video. + Err(error) if error.kind() == std::io::ErrorKind::UnexpectedEof => Ok(false), + answer => answer, + } +} + +/// The link a candidate makes once its content is confirmed. A candidate equal +/// to the link already recorded, path, size and time alike, is taken as +/// confirmed without opening it, unless the scan reads everything. +/// +/// A candidate the pass cannot read is passed over, as the core passes it +/// over, unless it is the clip already recorded: then the recorded link +/// stands, because a read that failed says nothing about what the file holds, +/// and a link dropped on an I/O error would come back at the next scan. +pub(super) fn confirm( + candidate: Candidate<'_>, + recorded: Option<&TrackClip>, + full: bool, +) -> Option { + let format = extension(split(candidate.name).1)?; + if !VIDEO_EXTENSIONS.contains(&format.as_str()) { + return None; + } + let unreadable = |error: std::io::Error| { + tracing::warn!(path = %candidate.name, %error, "a music video could not be read"); + recorded + .filter(|recorded| recorded.relative_path == candidate.name) + .cloned() + }; + let metadata = match std::fs::metadata(candidate.path) { + Ok(metadata) => metadata, + Err(error) => return unreadable(error), + }; + if !metadata.is_file() { + return None; + } + // From the one `stat` above, so a second one cannot fail apart from it, + // and stamped as a track is. + let (byte_size, modified_at) = stamp(&metadata); + let link = TrackClip { + relative_path: candidate.name.to_owned(), + format, + origin: candidate.origin, + byte_size, + modified_at, + }; + let unchanged = !full + && recorded.is_some_and(|recorded| { + recorded.relative_path == link.relative_path + && recorded.byte_size == link.byte_size + && recorded.modified_at == link.modified_at + }); + if unchanged { + return Some(link); + } + match holds_video(candidate.path, &link.format) { + Ok(video) => video.then_some(link), + Err(error) => unreadable(error), + } +} + +/// What one walk saw that the link pass needs. +pub(super) struct WalkedClips { + /// The audio files the walk kept, as `Discovery::paths`. + pub(super) tracks: Vec<(PathBuf, String)>, + pub(super) videos: Vec<(PathBuf, String)>, + pub(super) unreadable: Vec, + pub(super) incomplete: bool, + pub(super) scope: Option>, + pub(super) full: bool, +} + +/// The links that change: the link each walked track should have now, against +/// the one it has. +/// +/// A link is removed only where the walk could see that its clip went (RFC-018 +/// decision 3, as for a track): the clip file was walked and no longer +/// qualifies, or its place was walked and it was not there. A clip under a +/// folder the walk could not read, or a walk that could not say what it +/// missed, keeps the link. An excluded clip was not walked, so its link goes, +/// as an excluded track does. +pub(super) fn changes( + walked: &WalkedClips, + facts: &HashMap, +) -> Vec<(Uuid, Option)> { + let videos = Videos::new(&walked.videos); + let seen: HashSet = walked.videos.iter().map(|(_, name)| name.clone()).collect(); + let saw = Walked { + discovered: &seen, + unreadable: &walked.unreadable, + incomplete: walked.incomplete, + scope: walked.scope.as_deref(), + }; + let mut changes = Vec::new(); + for (path, name) in &walked.tracks { + // A track that failed to read, or that is not available, has no row + // to link from. + let Some(fact) = facts.get(name) else { + continue; + }; + let found = videos + .candidates(name, path) + .into_iter() + .find_map(|candidate| confirm(candidate, fact.clip.as_ref(), walked.full)); + match (found, &fact.clip) { + (Some(found), Some(recorded)) if found == *recorded => {} + (Some(found), _) => changes.push((fact.track_id, Some(found))), + (None, Some(recorded)) + if seen.contains(&recorded.relative_path) + || saw.saw_missing(&recorded.relative_path) => + { + changes.push((fact.track_id, None)); + } + (None, _) => {} + } + } + changes +} + +impl ScanManager { + /// Records the clip of every track the walk saw (RFC-029 decision 3), + /// after availability is settled so a track that went is not linked. + pub(super) async fn link_clips( + &self, + library_id: Uuid, + walked: WalkedClips, + ) -> anyhow::Result<()> { + let facts = self.db.track_clip_facts(library_id).await?; + let changes = tokio::task::spawn_blocking(move || changes(&walked, &facts)).await?; + if !changes.is_empty() { + tracing::debug!(%library_id, count = changes.len(), "music video links changed"); + self.db.apply_track_clips(&changes).await?; + } + Ok(()) + } +} diff --git a/src/library/scanner/clips/tests.rs b/src/library/scanner/clips/tests.rs new file mode 100644 index 00000000..d5f41e8b --- /dev/null +++ b/src/library/scanner/clips/tests.rs @@ -0,0 +1,307 @@ +use super::*; +use crate::library::scanner::discovery::{discover_audio, Reach}; + +fn ffmpeg(path: &Path, args: &[&str]) { + let output = std::process::Command::new("ffmpeg") + .args(["-hide_banner", "-loglevel", "error", "-y"]) + .args(args) + .arg(path) + .output() + .expect("FFmpeg is required for the music video fixtures"); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); +} + +fn tone(frequency: usize) -> String { + format!("sine=frequency={frequency}:duration=0.2") +} + +/// A moving picture with a soundtrack, in whatever container the name says. +fn video(path: &Path, frequency: usize) { + let tone = tone(frequency); + ffmpeg( + path, + &[ + "-f", + "lavfi", + "-i", + "color=c=blue:s=64x64:d=0.2", + "-f", + "lavfi", + "-i", + &tone, + "-shortest", + "-c:v", + "mpeg4", + "-c:a", + "aac", + ], + ); +} + +/// AAC alone. +fn audio_mp4(path: &Path, frequency: usize) { + let tone = tone(frequency); + ffmpeg(path, &["-f", "lavfi", "-i", &tone, "-c:a", "aac"]); +} + +/// Audio with a chapter's still picture: a `vide` track whose sample entry is +/// `png `, which is no clip. +fn still_mp4(path: &Path, frequency: usize) { + let tone = tone(frequency); + ffmpeg( + path, + &[ + "-f", + "lavfi", + "-i", + &tone, + "-f", + "lavfi", + "-i", + "color=c=red:s=16x16:d=0.2", + "-map", + "0", + "-map", + "1", + "-frames:v", + "1", + "-c:a", + "aac", + "-c:v", + "png", + "-f", + "mov", + ], + ); +} + +fn flac(path: &Path, frequency: usize) { + let tone = tone(frequency); + ffmpeg(path, &["-f", "lavfi", "-i", &tone, "-c:a", "flac"]); +} + +/// The EBML magic is all either side reads of a WebM or a Matroska file. +fn ebml(path: &Path) { + std::fs::write(path, [0x1a, 0x45, 0xdf, 0xa3, 0, 0, 0, 0]).unwrap(); +} + +/// A tree with every case decision 2 names, and what the rule answers for +/// each of its tracks. +fn fixture_tree(root: &Path) -> Vec<(&'static str, Option<(&'static str, &'static str)>)> { + for folder in ["A/Clips", "B/clips"] { + std::fs::create_dir_all(root.join(folder)).unwrap(); + } + // Beside the track. + flac(&root.join("A/Song.flac"), 300); + video(&root.join("A/Song.mp4"), 305); + // In its `Clips` folder. + flac(&root.join("A/Two.flac"), 310); + video(&root.join("A/Clips/Two.mp4"), 315); + // A video with no song: its own clip. + video(&root.join("A/Lone.mp4"), 320); + // An audio `.mp4` is a track, and no clip. + flac(&root.join("A/Audio.flac"), 330); + audio_mp4(&root.join("A/Audio.mp4"), 335); + // A chapter still is no clip. + flac(&root.join("A/Still.flac"), 340); + still_mp4(&root.join("A/Still.mp4"), 345); + // The extension order: `.mov` before `.mkv`. + flac(&root.join("A/Order.flac"), 350); + ebml(&root.join("A/Order.mkv")); + video(&root.join("A/Order.mov"), 355); + // The first candidate fails its content check, the next one is taken. + flac(&root.join("A/Fallback.flac"), 360); + audio_mp4(&root.join("A/Fallback.mp4"), 365); + ebml(&root.join("A/Fallback.webm")); + // Case folded, on the folder and on the name. + flac(&root.join("B/CASE.flac"), 370); + ebml(&root.join("B/clips/case.WEBM")); + // A track inside a `Clips` folder is offered none of its neighbours. + flac(&root.join("A/Clips/Inner.flac"), 380); + ebml(&root.join("A/Clips/Inner.webm")); + // A video track beside a video of its name. + video(&root.join("A/Pair.mp4"), 390); + ebml(&root.join("A/Pair.webm")); + vec![ + ("A/Audio.flac", None), + ("A/Audio.mp4", None), + ("A/Clips/Inner.flac", None), + ("A/Fallback.flac", Some(("A/Fallback.webm", "sibling"))), + ("A/Fallback.mp4", Some(("A/Fallback.webm", "sibling"))), + ("A/Lone.mp4", Some(("A/Lone.mp4", "itself"))), + ("A/Order.flac", Some(("A/Order.mov", "sibling"))), + ("A/Pair.mp4", Some(("A/Pair.webm", "sibling"))), + ("A/Song.flac", Some(("A/Song.mp4", "sibling"))), + ("A/Still.flac", None), + ("A/Still.mp4", None), + ("A/Two.flac", Some(("A/Clips/Two.mp4", "clips_dir"))), + ("B/CASE.flac", Some(("B/clips/case.WEBM", "clips_dir"))), + ] +} + +/// RFC-029 decision 2: the server's matcher answers what the core's +/// `find_clip` answers, for every track of a tree that holds each case the +/// rule distinguishes. A core release that changes the rule fails here +/// before it changes a catalogue. +#[test] +fn the_matcher_answers_what_find_clip_answers() { + let temp = tempfile::tempdir().unwrap(); + let root = std::fs::canonicalize(temp.path()).unwrap(); + let expected = fixture_tree(&root); + let walk = discover_audio( + &Reach { + root: &root, + follow_links: false, + link_roots: &[], + libraries: &[], + }, + None, + ) + .unwrap(); + let videos = Videos::new(&walk.videos); + let mut answers = Vec::new(); + for (path, name) in &walk.paths { + let ours = videos + .candidates(name, path) + .into_iter() + .find_map(|candidate| confirm(candidate, None, true)) + .map(|link| (link.relative_path, link.origin.to_owned())); + let core = waveflow_core::scanner::clips::find_clip(path).map(|(clip, origin)| { + let relative = clip + .strip_prefix(&root) + .unwrap() + .to_string_lossy() + .replace('\\', "/"); + ( + relative, + serde_json::to_value(origin) + .unwrap() + .as_str() + .unwrap() + .to_owned(), + ) + }); + assert_eq!(ours, core, "{name}"); + answers.push((name.clone(), ours)); + } + let expected: Vec<(String, Option<(String, String)>)> = expected + .into_iter() + .map(|(track, clip)| { + ( + track.to_owned(), + clip.map(|(path, origin)| (path.to_owned(), origin.to_owned())), + ) + }) + .collect(); + assert_eq!(answers, expected, "the tree holds what it says it holds"); +} + +fn link(relative_path: &str) -> TrackClip { + TrackClip { + relative_path: relative_path.to_owned(), + format: "mp4".to_owned(), + origin: "clips_dir", + byte_size: 1, + modified_at: 1, + } +} + +/// A track `A/Song.flac` linked to `A/Clips/Song.mp4`, whose clip this walk +/// did not see. +fn unseen_clip(walked: WalkedClips) -> Vec<(Uuid, Option)> { + let track = Uuid::new_v4(); + let facts = HashMap::from([( + "A/Song.flac".to_owned(), + TrackClipFacts { + track_id: track, + clip: Some(link("A/Clips/Song.mp4")), + }, + )]); + changes(&walked, &facts) +} + +fn walked() -> WalkedClips { + WalkedClips { + tracks: vec![( + PathBuf::from("/nowhere/A/Song.flac"), + "A/Song.flac".to_owned(), + )], + videos: Vec::new(), + unreadable: Vec::new(), + incomplete: false, + scope: None, + full: false, + } +} + +/// A link goes only where the walk could see its clip go: a clip under a +/// folder the walk could not read, or a walk that could not say what it +/// missed, keeps it. +#[test] +fn a_link_goes_only_when_the_walk_saw_its_clip_go() { + let gone = unseen_clip(walked()); + assert_eq!(gone.len(), 1); + assert_eq!( + gone[0].1, None, + "the clip's folder was walked, and it was not there" + ); + + let unreadable = unseen_clip(WalkedClips { + unreadable: vec!["A/Clips".to_owned()], + ..walked() + }); + assert!(unreadable.is_empty(), "the Clips folder could not be read"); + + let incomplete = unseen_clip(WalkedClips { + incomplete: true, + ..walked() + }); + assert!( + incomplete.is_empty(), + "the walk could not say what it missed" + ); +} + +/// A clip the pass cannot read keeps its recorded link: the failed read says +/// nothing about the file. A file read whole that holds no video loses it, and +/// a file too short for its header is such a file, not a failed read. +#[test] +fn a_clip_that_cannot_be_read_keeps_its_link() { + let temp = tempfile::tempdir().unwrap(); + let candidate = |path, name| Candidate { + path, + name, + origin: "sibling", + }; + let recorded = TrackClip { + origin: "sibling", + ..link("A/Song.webm") + }; + + let missing = temp.path().join("Song.webm"); + let cannot_read = candidate(&missing, "A/Song.webm"); + assert_eq!( + confirm(cannot_read, Some(&recorded), true), + Some(recorded.clone()) + ); + assert_eq!( + confirm(cannot_read, None, true), + None, + "nothing recorded to keep" + ); + let other = link("A/Clips/Song.mp4"); + assert_eq!( + confirm(cannot_read, Some(&other), true), + None, + "another clip's link" + ); + + let short = temp.path().join("Short.webm"); + std::fs::write(&short, [0x1a, 0x45]).unwrap(); + let truncated = candidate(&short, "A/Song.webm"); + assert_eq!(confirm(truncated, Some(&recorded), true), None); +} diff --git a/src/library/scanner/discovery/mod.rs b/src/library/scanner/discovery/mod.rs index 170f3222..c8a9d4b3 100644 --- a/src/library/scanner/discovery/mod.rs +++ b/src/library/scanner/discovery/mod.rs @@ -149,6 +149,10 @@ pub(super) struct Unreadable { /// folders it could not read, relative to the root. pub(super) struct Discovery { pub(super) paths: Vec<(PathBuf, String)>, + /// The video files, named the same way and in the same order: never + /// indexed, only matched against the tracks (RFC-029 decision 3). An + /// `.mp4` is in both lists, since a video one may be a track. + pub(super) videos: Vec<(PathBuf, String)>, pub(super) unreadable: Vec, /// An error named no path inside the root, so the walk cannot say which /// tracks it missed: none may be marked missing. @@ -533,6 +537,7 @@ pub(super) fn discover_audio( .collect(), }; let mut paths = Vec::new(); + let mut videos = Vec::new(); let mut incomplete = false; for (start, base) in starts { let entries = WalkDir::new(&start) @@ -590,6 +595,9 @@ pub(super) fn discover_audio( .extension() .and_then(|value| value.to_str()) .is_some_and(super::indexes_extension); + if waveflow_core::scanner::clips::is_video_extension(&path) { + videos.push((path.clone(), name.clone())); + } if supported { paths.push((path, name)); } @@ -601,6 +609,9 @@ pub(super) fn discover_audio( let mut read = HashSet::new(); paths.retain(|(path, _)| read.insert(path.clone())); drop_clips(&mut paths); + videos.sort_by(|left, right| left.1.cmp(&right.1)); + let mut read = HashSet::new(); + videos.retain(|(path, _)| read.insert(path.clone())); let walk = walk.into_inner(); if walk.skipped_links > LOGGED_LINKS { tracing::info!( @@ -610,6 +621,7 @@ pub(super) fn discover_audio( } Ok(Discovery { paths, + videos, unreadable: walk.unreadable, incomplete: incomplete || walk.incomplete, excluded: walk.excluded, @@ -674,7 +686,7 @@ impl Walked<'_> { /// track there is never one it saw missing — which is what keeps a scoped /// scan from moving the identity of a track it never looked for onto a /// file it found. - fn saw_missing(&self, relative_path: &str) -> bool { + pub(super) fn saw_missing(&self, relative_path: &str) -> bool { !self.incomplete && self .scope diff --git a/src/library/scanner/extract/mod.rs b/src/library/scanner/extract/mod.rs index f9d4b8e5..530a4ac1 100644 --- a/src/library/scanner/extract/mod.rs +++ b/src/library/scanner/extract/mod.rs @@ -58,14 +58,19 @@ pub(super) fn scan_file( /// A file's size and modification time, as `extract_file` records them. fn file_stamp(path: &Path) -> Option<(i64, i64)> { - let metadata = fs::metadata(path).ok()?; + fs::metadata(path).ok().map(|metadata| stamp(&metadata)) +} + +/// The size and modification time a `stat` already gave, in milliseconds, +/// `0` for a time the system cannot tell. +pub(super) fn stamp(metadata: &fs::Metadata) -> (i64, i64) { let modified_at = metadata .modified() .ok() .and_then(|value| value.duration_since(UNIX_EPOCH).ok()) .map(|value| value.as_millis() as i64) .unwrap_or(0); - Some((metadata.len() as i64, modified_at)) + (metadata.len() as i64, modified_at) } /// The two lyrics sidecars a scan reads beside an audio file, by size and diff --git a/src/library/scanner/job.rs b/src/library/scanner/job.rs index 4db5fa94..3ae4a51b 100644 --- a/src/library/scanner/job.rs +++ b/src/library/scanner/job.rs @@ -6,6 +6,7 @@ use std::{collections::HashSet, path::PathBuf, sync::Arc}; use futures_util::{stream, StreamExt}; use uuid::Uuid; +use super::clips::WalkedClips; use super::discovery::{discover_audio, unclaimed, Discovery, Reach, Walked}; use super::extract::{scan_file, Scanned}; use super::{normalised_scope, ScanManager, ScanProgress}; @@ -69,6 +70,7 @@ impl ScanManager { } let Discovery { paths, + videos, unreadable, incomplete, excluded, @@ -100,6 +102,16 @@ impl ScanManager { .collect(); let discovered: HashSet = paths.iter().map(|(_, relative)| relative.clone()).collect(); + // The link pass needs the walk's tracks after the reads have consumed + // them, and is told nothing the walk did not see (RFC-029 decision 3). + let clips = WalkedClips { + tracks: paths.clone(), + videos, + unreadable: unreadable_folders.clone(), + incomplete, + scope: scope.clone(), + full, + }; self.db .start_walked_scan_job( scan_id, @@ -339,6 +351,7 @@ impl ScanManager { .mark_unseen_unavailable_within(library.id, scan_id, scope.as_deref()) .await? }; + self.link_clips(library.id, clips).await?; // After availability is settled, not before: the album and artist // identifiers are a majority vote over the tracks that are still there, // so a file that vanished must stop voting first. diff --git a/src/library/scanner/mod.rs b/src/library/scanner/mod.rs index 1d88b76e..851db474 100644 --- a/src/library/scanner/mod.rs +++ b/src/library/scanner/mod.rs @@ -1,6 +1,7 @@ //! Server-authoritative filesystem scanner with SSE-ready progress events. pub(crate) mod chapter_guard; +mod clips; mod discovery; mod extract; mod job; diff --git a/src/storage/catalog/clips.rs b/src/storage/catalog/clips.rs new file mode 100644 index 00000000..a17af511 --- /dev/null +++ b/src/storage/catalog/clips.rs @@ -0,0 +1,131 @@ +//! A track's music video as the scan recorded it (RFC-029 decision 3): read +//! once per scan, then the rows that changed written back. + +use sqlx::Row; +use uuid::Uuid; + +use crate::storage::database::Database; + +use super::parse_uuid; + +/// The link a track has to its clip: the file, relative to the library root, +/// and what the next scan compares to take it as confirmed without opening it. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct TrackClip { + pub relative_path: String, + /// The file's extension, lower-cased: `mp4`, `m4v`, `mov`, `webm`, `mkv`. + pub format: String, + /// `sibling`, `clips_dir` or `itself`. + pub origin: &'static str, + pub byte_size: i64, + pub modified_at: i64, +} + +/// One available track of a library and the link it has now, if any. +#[derive(Debug, Clone)] +pub struct TrackClipFacts { + pub track_id: Uuid, + pub clip: Option, +} + +/// Rows written per transaction, so a library of many clips does not hold the +/// writer gate for its whole pass. +const CLIP_BATCH: usize = 200; + +fn origin(value: &str) -> Result<&'static str, sqlx::Error> { + match value { + "sibling" => Ok("sibling"), + "clips_dir" => Ok("clips_dir"), + "itself" => Ok("itself"), + other => Err(sqlx::Error::Decode( + format!("unknown clip origin {other:?}").into(), + )), + } +} + +impl Database { + /// Every available track of the library by its path, with the link it has. + /// One query per scan, as `track_skip_facts` is. + pub async fn track_clip_facts( + &self, + library_id: Uuid, + ) -> Result, sqlx::Error> { + let rows = sqlx::query( + "SELECT t.id, t.relative_path, c.relative_path AS clip_path, c.format, c.origin, \ + c.byte_size, c.modified_at \ + FROM track t LEFT JOIN track_clip c ON c.track_id = t.id \ + WHERE t.library_id = ? AND t.is_available = 1", + ) + .bind(library_id.to_string()) + .fetch_all(self.pool()) + .await?; + let mut facts = std::collections::HashMap::with_capacity(rows.len()); + for row in rows { + let clip = match row.try_get::, _>("clip_path")? { + Some(relative_path) => Some(TrackClip { + relative_path, + format: row.try_get("format")?, + origin: origin(&row.try_get::("origin")?)?, + byte_size: row.try_get("byte_size")?, + modified_at: row.try_get("modified_at")?, + }), + None => None, + }; + facts.insert( + row.try_get("relative_path")?, + TrackClipFacts { + track_id: parse_uuid(row.try_get("id")?)?, + clip, + }, + ); + } + Ok(facts) + } + + /// Writes the links a scan's pass changed: a link set or replaced, or, for + /// `None`, removed. `library_id` is read from the track in the writing + /// transaction, never taken from the caller, as `track_canvas` does it; a + /// track deleted since the pass read it writes nothing. + pub async fn apply_track_clips( + &self, + changes: &[(Uuid, Option)], + ) -> Result<(), sqlx::Error> { + for batch in changes.chunks(CLIP_BATCH) { + let writer = self.writer_guard().await; + let mut tx = self.begin_write(&writer).await?; + for (track_id, clip) in batch { + match clip { + Some(clip) => { + sqlx::query( + "INSERT INTO track_clip \ + (track_id, library_id, relative_path, format, origin, byte_size, \ + modified_at) \ + SELECT id, library_id, ?, ?, ?, ?, ? FROM track WHERE id = ? \ + ON CONFLICT (track_id) DO UPDATE SET \ + relative_path = excluded.relative_path, \ + format = excluded.format, origin = excluded.origin, \ + byte_size = excluded.byte_size, \ + modified_at = excluded.modified_at", + ) + .bind(&clip.relative_path) + .bind(&clip.format) + .bind(clip.origin) + .bind(clip.byte_size) + .bind(clip.modified_at) + .bind(track_id.to_string()) + .execute(&mut *tx) + .await?; + } + None => { + sqlx::query("DELETE FROM track_clip WHERE track_id = ?") + .bind(track_id.to_string()) + .execute(&mut *tx) + .await?; + } + } + } + tx.commit().await?; + } + Ok(()) + } +} diff --git a/src/storage/catalog/mod.rs b/src/storage/catalog/mod.rs index 753d0e2f..5af8b981 100644 --- a/src/storage/catalog/mod.rs +++ b/src/storage/catalog/mod.rs @@ -7,6 +7,7 @@ use uuid::Uuid; mod apply; mod availability; +mod clips; mod credits; mod derivations; mod identity; @@ -17,6 +18,7 @@ mod tracks; pub use apply::{ApplyOutcome, ArtworkInput, CatalogApply, CatalogTrackInput}; pub use availability::SkipFacts; +pub use clips::{TrackClip, TrackClipFacts}; pub use identity::{track_pid, ExistingTrack}; pub use libraries::{LibraryAccess, LibraryRecord, LibraryScanSettings}; pub use scan_jobs::ScanJobRecord; diff --git a/tests/scanner/music_videos.rs b/tests/scanner/music_videos.rs index d4f9e0ef..88272439 100644 --- a/tests/scanner/music_videos.rs +++ b/tests/scanner/music_videos.rs @@ -136,4 +136,107 @@ async fn a_scan_of_a_clips_folder_walks_its_parent() { let record = settled(&state, owner, scan).await; assert_eq!(record.status, "completed", "{:?}", record.message); assert_eq!(available_paths(&state).await, ["Album/Song.flac"]); + assert_eq!( + links(&state).await, + [link("Album/Song.flac", "Album/Clips/Song.mp4", "clips_dir")], + "and links the clip to the song it found there" + ); +} + +/// Every recorded link as `(track, clip, origin)`, in track order. +async fn links(state: &waveflow_server::AppState) -> Vec<(String, String, String)> { + sqlx::query_as( + "SELECT t.relative_path, c.relative_path, c.origin \ + FROM track_clip c JOIN track t ON t.id = c.track_id \ + WHERE c.library_id = t.library_id ORDER BY t.relative_path", + ) + .fetch_all(state.db.pool()) + .await + .unwrap() +} + +fn link(track: &str, clip: &str, origin: &str) -> (String, String, String) { + (track.to_owned(), clip.to_owned(), origin.to_owned()) +} + +/// RFC-029 decision 3: the scan records the clip of each track, by the three +/// origins of the desktop's rule. +#[tokio::test] +async fn a_scan_records_each_track_s_music_video() { + let (_temp, state, owner, library, root) = incremental_library("linked", |music| { + std::fs::create_dir_all(music.join("Album/Clips")).unwrap(); + write_tagged_flac(&music.join("Album/Song.flac"), "Song", "Album", 600); + write_video_mp4(&music.join("Album/Song.mp4"), 605); + write_tagged_flac(&music.join("Album/Two.flac"), "Two", "Album", 610); + write_video_mp4(&music.join("Album/Clips/Two.mp4"), 615); + write_video_mp4(&music.join("Album/Lone.mp4"), 620); + write_tagged_flac(&music.join("Album/Audio.flac"), "Audio", "Album", 630); + write_audio_mp4(&music.join("Album/Audio.mp4"), 635); + }) + .await; + scan_once(&state, owner, library).await; + + assert_eq!( + links(&state).await, + [ + link("Album/Lone.mp4", "Album/Lone.mp4", "itself"), + link("Album/Song.flac", "Album/Song.mp4", "sibling"), + link("Album/Two.flac", "Album/Clips/Two.mp4", "clips_dir"), + ] + ); + let (format, byte_size): (String, i64) = sqlx::query_as( + "SELECT format, byte_size FROM track_clip WHERE relative_path = 'Album/Song.mp4'", + ) + .fetch_one(state.db.pool()) + .await + .unwrap(); + assert_eq!(format, "mp4"); + assert_eq!( + byte_size, + std::fs::metadata(root.join("Album/Song.mp4")) + .unwrap() + .len() as i64 + ); +} + +/// The link follows the disk from scan to scan: a clip added beside a track +/// the incremental scan skips is recorded, an excluded one is not, and one +/// deleted is forgotten. +#[tokio::test] +async fn a_link_follows_the_disk_from_scan_to_scan() { + let (_temp, state, owner, library, root) = incremental_library("follows", |music| { + std::fs::create_dir_all(music.join("Album/Clips")).unwrap(); + write_tagged_flac(&music.join("Album/Song.flac"), "Song", "Album", 700); + }) + .await; + scan_once(&state, owner, library.clone()).await; + assert!(links(&state).await.is_empty()); + + let clip = root.join("Album/Clips/Song.mp4"); + write_video_mp4(&clip, 705); + scan_once(&state, owner, library.clone()).await; + let linked = [link("Album/Song.flac", "Album/Clips/Song.mp4", "clips_dir")]; + assert_eq!( + links(&state).await, + linked, + "added beside a track the scan skipped" + ); + + std::fs::write(root.join(".waveflowignore"), "Clips/\n").unwrap(); + scan_once(&state, owner, library.clone()).await; + assert!( + links(&state).await.is_empty(), + "an excluded clip is not seen" + ); + + std::fs::remove_file(root.join(".waveflowignore")).unwrap(); + scan_once(&state, owner, library.clone()).await; + assert_eq!(links(&state).await, linked); + + std::fs::remove_file(&clip).unwrap(); + scan_once(&state, owner, library).await; + assert!( + links(&state).await.is_empty(), + "a deleted clip is forgotten" + ); }