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
32 changes: 22 additions & 10 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,31 @@ out first, whether or not it breaks a compile.

## [Unreleased]

**A response grows one field.** Every native track (`SongItem`, and through
it `TrackDetail`, the listings and the catalogue snapshot) carries `clip`:
`{ "format", "byte_size" }` or `null`. The Subsonic façade is untouched.

### 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
- **A track's music video** ([RFC-029](docs/rfcs/RFC-029-track-music-video.md)).
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.
distinguishes.
- The scan records the link in a new table, `track_clip`, and drops it only
where it could see the clip go, so a `Clips` folder that cannot be read
keeps its links. A link that changes is the track's `upsert` on the
change feed.
- `GET /api/v2/tracks/{id}/clip`, `POST /api/v2/tracks/{id}/clip-ticket` and
`GET /api/v2/clip-stream/{ticket}` serve the file as it is, whole or by
range, never transcoded, to whoever may play the track, re-checked at
every request. The ticket is a fourth kind, `0x04`, which opens neither
the audio nor a canvas, nor is opened by theirs; no ticket minted before
the upgrade stops working. Its path is redacted from traces as the other
tickets' are.

### Fixed

Expand Down
41 changes: 41 additions & 0 deletions docs/guides/api-v2-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -822,6 +822,47 @@ The ticket works like the audio one, and neither opens the other. Minting it
checks the link, so it is also how a client asks whether a track has a canvas:
a track without one answers `404`.

### A track's music video

A music video is a video file the operator put in the library beside a track,
named like it ([RFC-029](../rfcs/RFC-029-track-music-video.md)). The scan finds
it, as the desktop app does for a local track, and records the link. There is no
route that places or removes one: the disk is the authority, and the operations
guide says where the files go.

Every track says whether it has one, in its `clip` field: the container and
the size, or `null`. Nothing names the file. A link that appears, changes or
goes reaches the change feed as the track's `upsert`, so a client re-reads the
track.

```json
"clip": { "format": "mp4", "byte_size": 182734112 }
```

| Route | Purpose |
|---|---|
| `GET /api/v2/tracks/{track_id}/clip` | The clip the track has now, whole or by range |
| `POST /api/v2/tracks/{track_id}/clip-ticket` | A URL a `<video>` element can play |
| `GET /api/v2/clip-stream/{ticket}` | What that URL serves |

The file is served as it is, never transcoded: `video/mp4` for `mp4` and
`m4v`, `video/quicktime` for `mov`, `video/webm` and `video/x-matroska`.
Whether a player can open the container is the player's to report. A range
answers `206`, as the audio's does. The ticket's URL is relative, like the
audio's: prepend the base URL you authenticated against, and refuse an
absolute or protocol-relative answer. Its lifetime is the audio ticket's, and
the audio, canvas and clip tickets do not open each other's routes.

Whoever may play the track may watch its clip, re-checked at every request
and every redemption. A track without a clip, one that is unavailable or not
yours, a clip deleted from the disk since the scan, and a ticket that is
expired, forged or of another kind all answer the same `404`. A ticket that
expires while a clip is paused answers `404` to the next range request: mint a
new one and resume at the clip's position, and conclude that the track has no
clip only when minting answers `404` too.

The Subsonic façade says nothing of a clip: a song keeps `isVideo="false"`.

## User-data mutations and idempotency

User data written through the native API and Subsonic façade uses the same
Expand Down
36 changes: 36 additions & 0 deletions docs/guides/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -769,6 +769,42 @@ turns unavailable at the end of the scan, exactly as if the file had been
deleted, and comes back under the same identity when the rule is removed. The
scan's `excluded` counter says how many entries were left out.

### Music videos

A track's music video is a video file named like the track, its extension
aside and case ignored. Put it beside the track, or in a folder called `Clips`
beside it ([RFC-029](../rfcs/RFC-029-track-music-video.md)):

```text
Album/
01 Song.flac
01 Song.mp4 ← this track's clip
Clips/
02 Other.webm ← 02 Other.flac's clip
02 Other.flac
```

The rule is the desktop app's, so a library it plays from its own disk and the
same library on this server show the same clips. The containers are `mp4`,
`m4v`, `mov`, `webm` and `mkv`, tried in that order when a track has several,
and the content is checked: an `mp4`, `m4v` or `mov` must hold a moving
picture. A `webm` or `mkv` is only checked for its header, as on the desktop.
A video `.mp4` with no track of its name is a track itself, and its own clip.

The scan records the link and serves the file as it is: nothing is transcoded,
remuxed or written beside it. Clients play it through the native API; the
Subsonic façade does not offer it.

**A video `.mp4` beside its song is not a track.** An `.mp4` is an audio
extension, so earlier versions indexed such a clip as a second track whose
sound was the clip's. The next scan after upgrading leaves it out, and that track
goes as a deleted file does, with whatever was recorded on it. An audio `.mp4`
always stays a track.

To keep clips off the server, put them where the scan does not go: a
`.waveflowignore` line `Clips/` leaves out every `Clips` folder. A `Clips`
folder the scan cannot read keeps the links it held.

### Symbolic links

By default a scan does not follow symbolic links. It no longer skips them in
Expand Down
5 changes: 4 additions & 1 deletion docs/rfcs/RFC-029-track-music-video.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,10 @@
(the core pin), [#450](https://github.com/InstaZDLL/waveflow-server/pull/450)
(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
and 3, the link the scan records),
[#452](https://github.com/InstaZDLL/waveflow-server/pull/452) (decisions 5
to 8, the routes, the ticket and the `clip` field); the web client 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
Expand Down
7 changes: 6 additions & 1 deletion src/app/openapi.rs
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,10 @@ pub const SCALAR_PATH: &str = "/reference";
media::put_canvas,
media::delete_canvas,
media::create_canvas_ticket,
media::canvas_with_ticket
media::canvas_with_ticket,
media::clip_for_track,
media::create_clip_ticket,
media::clip_with_ticket
),
components(schemas(
api::ProbeResponse,
Expand Down Expand Up @@ -224,6 +227,7 @@ pub const SCALAR_PATH: &str = "/reference";
services::GenreItem,
services::LibraryMember,
services::SongItem,
services::ClipSummary,
services::TrackDetail,
services::TrackOverrides,
services::TrackOverrideValues,
Expand Down Expand Up @@ -467,6 +471,7 @@ pub(super) const PUBLIC_OPERATIONS: &[(&str, &str)] = &[
("/api/v2/oauth/token", "post"),
("/api/v2/stream/{ticket}", "get"),
("/api/v2/canvas-stream/{ticket}", "get"),
("/api/v2/clip-stream/{ticket}", "get"),
// The Last.fm return, and the one entry here that is not a ticket. It is
// reached by a person's browser coming back from another site, with no
// `Authorization` header and — every cookie of this server being
Expand Down
3 changes: 2 additions & 1 deletion src/app/router.rs
Original file line number Diff line number Diff line change
Expand Up @@ -197,9 +197,10 @@ pub fn app(config: &Config, state: AppState) -> Router {
/// spellings means already holding the ticket, so it is hardening rather than a
/// disclosure route, and normalising here would put a second opinion about what
/// a path means next to the router's.
pub(super) const CREDENTIAL_BEARING_PREFIXES: [(&str, &str); 4] = [
pub(super) const CREDENTIAL_BEARING_PREFIXES: [(&str, &str); 5] = [
("/api/v2/stream/", "/api/v2/stream/{redacted}"),
("/api/v2/canvas-stream/", "/api/v2/canvas-stream/{redacted}"),
("/api/v2/clip-stream/", "/api/v2/clip-stream/{redacted}"),
("/share/", "/share/{redacted}"),
// The Last.fm return. Its `{state}` is a single-use random worth a
// profile for a quarter of an hour, and the `token` Last.fm appends is
Expand Down
6 changes: 6 additions & 0 deletions src/auth/stream_ticket/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -39,18 +39,23 @@ pub enum TicketKind {
/// ticket naming the owner would open the owner's whole catalogue on the
/// routes that redeem the other two kinds.
ShareVisit,
/// A track's music video (RFC-029 decision 5): a file of hundreds of
/// megabytes beside the track's audio, so neither may open the other.
Clip,
}

impl TicketKind {
const AUDIO: u8 = 0x01;
const CANVAS: u8 = 0x02;
const SHARE_VISIT: u8 = 0x03;
const CLIP: u8 = 0x04;

const fn as_byte(self) -> u8 {
match self {
Self::Audio => Self::AUDIO,
Self::Canvas => Self::CANVAS,
Self::ShareVisit => Self::SHARE_VISIT,
Self::Clip => Self::CLIP,
}
}

Expand All @@ -61,6 +66,7 @@ impl TicketKind {
Self::AUDIO => Some(Self::Audio),
Self::CANVAS => Some(Self::Canvas),
Self::SHARE_VISIT => Some(Self::ShareVisit),
Self::CLIP => Some(Self::Clip),
_ => None,
}
}
Expand Down
8 changes: 7 additions & 1 deletion src/auth/stream_ticket/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ fn round_trip_returns_the_authorised_triple() {
TicketKind::Audio,
TicketKind::Canvas,
TicketKind::ShareVisit,
TicketKind::Clip,
] {
let user = Uuid::new_v4();
let track = Uuid::new_v4();
Expand All @@ -46,7 +47,12 @@ fn the_kinds_do_not_answer_for_each_other() {
let audio = mint(&secret, TicketKind::Audio, user, track, 1_000).unwrap();
let canvas = mint(&secret, TicketKind::Canvas, user, track, 1_000).unwrap();
let visit = mint(&secret, TicketKind::ShareVisit, user, track, 1_000).unwrap();
let clip = mint(&secret, TicketKind::Clip, user, track, 1_000).unwrap();
assert_ne!(audio, canvas, "the kind is inside the sealed payload");
assert_eq!(
verify(&secret, &clip, 999).map(|(kind, ..)| kind),
Some(TicketKind::Clip)
);
assert_eq!(
verify(&secret, &audio, 999).map(|(kind, ..)| kind),
Some(TicketKind::Audio)
Expand All @@ -69,7 +75,7 @@ fn an_unknown_kind_is_refused_even_under_the_right_key() {
// Sealed under the real key, correct length, live expiry: the kind byte
// is the only thing wrong with it. A forged ticket would prove nothing
// about this contract, since it already fails to decrypt.
for byte in [0x00, 0x04, 0xff] {
for byte in [0x00, 0x05, 0xff] {
let ticket = seal(&secret, &payload_with_kind(byte, user, track, 1_000));
assert_eq!(
verify(&secret, &ticket, 999),
Expand Down
Loading
Loading