From c28588a7d5ae2d418eb8bc9cd50ae20ab3b69107 Mon Sep 17 00:00:00 2001 From: InstaZDLL Date: Sat, 14 Nov 2026 19:29:27 +0100 Subject: [PATCH 1/2] fix(scanner): leave a music video out of the walk Signed-off-by: InstaZDLL --- CHANGELOG.md | 19 ++++ src/library/scanner/discovery/mod.rs | 49 ++++++++- src/library/scanner/discovery/tests.rs | 12 +++ tests/scanner/main.rs | 1 + tests/scanner/music_videos.rs | 139 +++++++++++++++++++++++++ 5 files changed, 219 insertions(+), 1 deletion(-) create mode 100644 tests/scanner/music_videos.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index 6787eb94..de81e33f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,25 @@ out first, whether or not it breaks a compile. ## [Unreleased] +### Fixed + +- **A music video beside its song is no longer a second track** + ([RFC-029](docs/rfcs/RFC-029-track-music-video.md) decision 4). `mp4` is + an audio extension, rightly, so a video named like its song, + `Album/Song.mp4` beside `Album/Song.flac` or in `Album/Clips/`, was indexed + as a track whose audio was the clip's soundtrack. The scan now leaves it + out, by the rule the desktop applies. An `.mp4` is left out only when a song + of its name sits beside it and the file really holds a moving picture: an + audio `.mp4` always stays a track, and so does a video with no song of its + name. A change in a `Clips` folder now scans the folder above it, where + the song is. + + **On a server that already indexed such a video**, the next scan finds that + track gone, as it would a deleted file: it becomes unavailable, then is + purged under the library's rules, and whatever a member had on it goes + with it: a favourite, a rating, plays, a playlist entry. It was never a + track; it was the clip of one, played without its picture. + ### Changed - **waveflow-core is pinned to its `v2.1.0` tag**, from `v2.0.0`. Two things diff --git a/src/library/scanner/discovery/mod.rs b/src/library/scanner/discovery/mod.rs index c3b07d16..170f3222 100644 --- a/src/library/scanner/discovery/mod.rs +++ b/src/library/scanner/discovery/mod.rs @@ -375,7 +375,8 @@ fn admit( pub(crate) const MAX_SCOPE_FOLDERS: usize = 64; /// A scope as a scoped walk may use it: folders relative to the root, spelled -/// with `/`, none of them nested in another, at most [`MAX_SCOPE_FOLDERS`]. +/// with `/`, none of them nested in another, at most [`MAX_SCOPE_FOLDERS`]. A +/// `Clips` folder stands for the folder above it. /// /// `None` — the whole library — for anything that is not plainly such a list: /// an empty folder (the root itself), a `..`, an absolute path, too many @@ -397,6 +398,15 @@ pub(crate) fn normalised_scope(scope: &[String]) -> Option> { { return None; } + // A clip in `Album/Clips/` is told from a track only by the song in + // `Album/` (RFC-029 decision 3): a walk of the `Clips` folder alone + // would index it. Its parent is walked instead, the root when there is + // none above it. + let folder = match folder.rsplit_once('/') { + Some((parent, last)) if is_clips_dir(last) => parent, + None if is_clips_dir(folder) => return None, + _ => folder, + }; folders.push(folder.to_owned()); } folders.sort(); @@ -418,6 +428,10 @@ pub(crate) fn normalised_scope(scope: &[String]) -> Option> { (!kept.is_empty() && kept.len() <= MAX_SCOPE_FOLDERS).then_some(kept) } +fn is_clips_dir(name: &str) -> bool { + waveflow_core::scanner::clips::is_clips_dir_name(std::ffi::OsStr::new(name)) +} + /// Where a scoped walk of `folder` starts, and how deep below the root that /// is — or `None` when there is nothing to walk there. /// @@ -586,6 +600,7 @@ pub(super) fn discover_audio( // found directly: the first name in catalogue order keeps it. let mut read = HashSet::new(); paths.retain(|(path, _)| read.insert(path.clone())); + drop_clips(&mut paths); let walk = walk.into_inner(); if walk.skipped_links > LOGGED_LINKS { tracing::info!( @@ -602,6 +617,38 @@ pub(super) fn discover_audio( }) } +/// Takes a track's music video out of the walk (RFC-029 decision 4): an `.mp4` +/// that the desktop's rule makes the clip of a file of the same name, and +/// whose content holds a moving picture. `mp4` is an audio extension, rightly, +/// so such a clip would otherwise be indexed as a second track whose audio is +/// the clip's soundtrack. +/// +/// The rule is the core's `drop_clips`, run on the catalogue names, which +/// are the folders as the library shows them, so it decides here exactly as it +/// does in the desktop's walk. An `.mp4` with no video stays a track whatever +/// its neighbours, and so does a video one with no song of its name. Only the +/// content check reads the disk, and only for a candidate; a file it cannot read +/// stays a track. A track already indexed from such a file is then not +/// discovered, and goes the way of any vanished file. +fn drop_clips(paths: &mut Vec<(PathBuf, String)>) { + let mut names: Vec = paths.iter().map(|(_, name)| PathBuf::from(name)).collect(); + let files: std::collections::HashMap = paths + .iter() + .map(|(path, name)| (PathBuf::from(name), path.as_path())) + .collect(); + let dropped = waveflow_core::scanner::clips::drop_clips(&mut names, |name| { + files + .get(name) + .is_some_and(|path| waveflow_core::scanner::clips::file_has_video_track(path)) + }); + if dropped == 0 { + return; + } + tracing::debug!(count = dropped, "music videos left out of the walk"); + let kept: HashSet = names.into_iter().collect(); + paths.retain(|(_, name)| kept.contains(Path::new(name))); +} + /// What one walk saw, as relocation needs it: the files it found, what it /// could not look at, and — for a scoped walk — where it looked at all. pub(super) struct Walked<'a> { diff --git a/src/library/scanner/discovery/tests.rs b/src/library/scanner/discovery/tests.rs index 2e1a5307..e24077a3 100644 --- a/src/library/scanner/discovery/tests.rs +++ b/src/library/scanner/discovery/tests.rs @@ -137,6 +137,18 @@ fn a_scope_is_plain_folders_or_the_whole_library() { for whole in [&[""][..], &["a/../b"], &["/etc"], &["a//b"], &["."], &[]] { assert_eq!(super::normalised_scope(&folders(whole)), None, "{whole:?}"); } + // A `Clips` folder is its parent (RFC-029 decision 3), whatever its case, + // and at the root it is the whole library. A folder only named like one is + // not. + assert_eq!( + super::normalised_scope(&folders(&[ + "Album/Clips", + "Other/clips/", + "Live/Clips Live" + ])), + Some(folders(&["Album", "Live/Clips Live", "Other"])), + ); + assert_eq!(super::normalised_scope(&folders(&["Clips"])), None); let many: Vec = (0..=super::MAX_SCOPE_FOLDERS) .map(|index| format!("f{index}")) .collect(); diff --git a/tests/scanner/main.rs b/tests/scanner/main.rs index 8d386ea5..ca039f7e 100644 --- a/tests/scanner/main.rs +++ b/tests/scanner/main.rs @@ -22,6 +22,7 @@ mod exclusions; mod incremental; mod indexing; mod lifecycle; +mod music_videos; mod purges; mod scheduling; diff --git a/tests/scanner/music_videos.rs b/tests/scanner/music_videos.rs new file mode 100644 index 00000000..d4f9e0ef --- /dev/null +++ b/tests/scanner/music_videos.rs @@ -0,0 +1,139 @@ +//! A music video beside its song is not a track (RFC-029 decision 4). +//! +//! `mp4` is an audio extension, so before this a video dropped beside its song +//! as `Song.mp4` was indexed as a second track. The rule is the core's +//! `drop_clips`, as the desktop's walk applies it; these tests hold what it +//! keeps as much as what it drops, since real audio must never be lost to it. + +use super::*; + +/// An `.mp4` with a moving picture and a soundtrack, as a music video is. +fn write_video_mp4(path: &std::path::Path, frequency: usize) { + ffmpeg( + path, + &[ + "-f", + "lavfi", + "-i", + "color=c=blue:s=64x64:d=0.2", + "-f", + "lavfi", + "-i", + &format!("sine=frequency={frequency}:duration=0.2"), + "-shortest", + "-c:v", + "mpeg4", + "-c:a", + "aac", + ], + ); +} + +/// An `.mp4` holding nothing but AAC, which is a track whatever its name. +fn write_audio_mp4(path: &std::path::Path, frequency: usize) { + ffmpeg( + path, + &[ + "-f", + "lavfi", + "-i", + &format!("sine=frequency={frequency}:duration=0.2"), + "-c:a", + "aac", + ], + ); +} + +fn ffmpeg(path: &std::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) + ); +} + +#[tokio::test] +async fn a_music_video_beside_its_song_is_not_a_track() { + let (_temp, state, owner, library, _root) = incremental_library("videos", |music| { + std::fs::create_dir_all(music.join("Album/Clips")).unwrap(); + // The clip beside its song, and the clip in a `Clips` folder beside it. + write_tagged_flac(&music.join("Album/Song.flac"), "Song", "Album", 300); + write_video_mp4(&music.join("Album/Song.mp4"), 310); + write_tagged_flac(&music.join("Album/Other.flac"), "Other", "Album", 320); + write_video_mp4(&music.join("Album/Clips/Other.mp4"), 330); + // An audio `.mp4` beside a song of its name stays a track. + write_tagged_flac(&music.join("Album/Audio.flac"), "Audio", "Album", 340); + write_audio_mp4(&music.join("Album/Audio.mp4"), 350); + // A video with no song of its name is a track: a library of videos. + write_video_mp4(&music.join("Album/Lone.mp4"), 360); + // A `.webm` is no audio file, so it cannot make its namesake a clip: + // only the audio files of the walk take part in the rule. + write_video_mp4(&music.join("Album/Pair.mp4"), 370); + // Its content is never read: the EBML magic stands for a WebM. + std::fs::write( + music.join("Album/Pair.webm"), + [0x1a, 0x45, 0xdf, 0xa3, 0, 0, 0, 0], + ) + .unwrap(); + }) + .await; + scan_once(&state, owner, library).await; + + assert_eq!( + available_paths(&state).await, + [ + "Album/Audio.flac", + "Album/Audio.mp4", + "Album/Lone.mp4", + "Album/Other.flac", + "Album/Pair.mp4", + "Album/Song.flac", + ] + ); +} + +/// A server that indexed a clip as a track before this loses that track on the +/// next scan, as it would lose any file gone from the walk. +#[tokio::test] +async fn a_video_already_indexed_goes_once_its_song_is_beside_it() { + let (_temp, state, owner, library, root) = incremental_library("indexed", |music| { + std::fs::create_dir_all(music.join("Album")).unwrap(); + write_video_mp4(&music.join("Album/Song.mp4"), 400); + }) + .await; + scan_once(&state, owner, library.clone()).await; + assert_eq!(available_paths(&state).await, ["Album/Song.mp4"]); + + write_tagged_flac(&root.join("Album/Song.flac"), "Song", "Album", 410); + scan_once(&state, owner, library).await; + assert_eq!(available_paths(&state).await, ["Album/Song.flac"]); +} + +/// The watcher scopes a scan to the folder a change happened in. A clip dropped +/// into `Album/Clips/` is told from a track only by the song in `Album/`, so +/// that scan walks `Album/`. +#[tokio::test] +async fn a_scan_of_a_clips_folder_walks_its_parent() { + let (_temp, state, owner, library, root) = incremental_library("scoped", |music| { + std::fs::create_dir_all(music.join("Album/Clips")).unwrap(); + write_tagged_flac(&music.join("Album/Song.flac"), "Song", "Album", 500); + }) + .await; + scan_once(&state, owner, library.clone()).await; + + write_video_mp4(&root.join("Album/Clips/Song.mp4"), 510); + let scan = state + .scanner + .trigger_scoped(library, "watch", &["Album/Clips".to_owned()]) + .await + .unwrap(); + let record = settled(&state, owner, scan).await; + assert_eq!(record.status, "completed", "{:?}", record.message); + assert_eq!(available_paths(&state).await, ["Album/Song.flac"]); +} From 0be8f5764dc14053308974794ec2c66973de06a4 Mon Sep 17 00:00:00 2001 From: InstaZDLL Date: Sat, 14 Nov 2026 19:29:44 +0100 Subject: [PATCH 2/2] docs(rfcs): name what implements rfc-029 so far Signed-off-by: InstaZDLL --- docs/rfcs/RFC-029-track-music-video.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/rfcs/RFC-029-track-music-video.md b/docs/rfcs/RFC-029-track-music-video.md index 64d2d28b..75fd3b35 100644 --- a/docs/rfcs/RFC-029-track-music-video.md +++ b/docs/rfcs/RFC-029-track-music-video.md @@ -1,8 +1,11 @@ # RFC-029 — A track's music video - **Status**: Proposed -- **Implemented by**: nothing yet. The *Status* field above never flips in - this project; this line is the one that says what is running. +- **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 + *Status* field above never flips in this project; this line is the one that + says what is running. - **Date**: 2026-11-14 - **Authors**: the WaveFlow project - **Depends on**: [RFC-002](RFC-002-waveflow-server-v2.md),