Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 5 additions & 2 deletions docs/rfcs/RFC-029-track-music-video.md
Original file line number Diff line number Diff line change
@@ -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),
Expand Down
49 changes: 48 additions & 1 deletion src/library/scanner/discovery/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -397,6 +398,15 @@ pub(crate) fn normalised_scope(scope: &[String]) -> Option<Vec<String>> {
{
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();
Expand All @@ -418,6 +428,10 @@ pub(crate) fn normalised_scope(scope: &[String]) -> Option<Vec<String>> {
(!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.
///
Expand Down Expand Up @@ -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!(
Expand All @@ -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<PathBuf> = paths.iter().map(|(_, name)| PathBuf::from(name)).collect();
let files: std::collections::HashMap<PathBuf, &Path> = 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<PathBuf> = 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> {
Expand Down
12 changes: 12 additions & 0 deletions src/library/scanner/discovery/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> = (0..=super::MAX_SCOPE_FOLDERS)
.map(|index| format!("f{index}"))
.collect();
Expand Down
1 change: 1 addition & 0 deletions tests/scanner/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ mod exclusions;
mod incremental;
mod indexing;
mod lifecycle;
mod music_videos;
mod purges;
mod scheduling;

Expand Down
139 changes: 139 additions & 0 deletions tests/scanner/music_videos.rs
Original file line number Diff line number Diff line change
@@ -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"]);
}
Loading