Files
minstrel/web/src/lib/player/events.svelte.ts
T
bvandeusenandClaude Opus 5.5 466912e202
release / govulncheck (push) Successful in 25s
release / web (push) Successful in 1m21s
release / go (push) Successful in 1m47s
release / integration (push) Successful in 4m35s
release / android (push) Successful in 7m5s
release / Build signed APK (releases and dev) (push) Successful in 7m16s
release / Attach APK to the Release (tag releases only) (push) Skipped
release / Build + push container image (push) Successful in 1m1s
release / Verify release artifacts (tag releases only) (push) Skipped
docs: plan-era "v1", "Task N" and "Phase N" wording restated as facts (#6277)
The marker list behind the earlier server and web passes did not catch
"for v1", "Task 5", "Phase 2" or "today: Flutter". Those comments now say
what the code does.

Corrected: coverart said "both v1 providers" ship on. There are four
providers (MBCAA, TheAudioDB, Deezer, Last.fm), and Last.fm, which needs a
key, ships off.

Non-comment tokens unchanged against HEAD: 10 Go files, 7 TS/Svelte files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 13:05:03 -04:00

140 lines
5.4 KiB
TypeScript

import { player } from './store.svelte';
import { api } from '#lib/api/client.js';
import { getOrCreateClientId } from './clientId';
import type { PlayStartedResponse, EventOkResponse } from '#lib/api/types.js';
// useEventsDispatcher installs $effect-based watchers that emit play events
// to /api/events. Call once from +layout.svelte's mount.
//
// The dispatcher is a small state machine over (current track id, state):
// - First transition into 'playing' for a new track → POST play_started.
// - Track id changes while a play is open → close the prior row with
// play_ended carrying the actual position played to. Server applies
// its skip rule (skip_max_completion_ratio + skip_max_duration_played_ms,
// default 50%/30s) and decides was_skipped from that.
// - Natural completion (state moves from 'playing' to 'paused' AND
// position >= duration > 0) → POST play_ended on the open row.
// - pagehide with a live row → navigator.sendBeacon a play_ended with
// the last position. The server's rule still classifies skip-vs-not.
//
// The skip-vs-ended call is the server's, as on Android: a client-side
// "within 3s of duration" rule would leave the server's threshold dead and
// treat every "next" tap as a skip even after most of the track played.
export function useEventsDispatcher(): void {
let openPlayEventId: string | null = null;
let openTrackId: string | null = null;
// openLastPositionMs tracks the *open row's* track and is updated ONLY while
// that track is current — so a track change (which synchronously resets the
// store's position to 0 and duration to 0) can't clobber it before the close
// branch reads it. The pagehide + natural-end branches can read
// player.position directly because their current track is still the open one
// at fire time.
let openLastPositionMs = 0;
let prevTrackId: string | null = null;
let prevState: string | null = null;
const clientId = getOrCreateClientId();
$effect(() => {
if (openTrackId && player.current?.id === openTrackId) {
openLastPositionMs = Math.round(player.position * 1000);
}
});
// Main state machine. Reacts only to (current track id, state) transitions.
$effect(() => {
const t = player.current;
const s = player.state;
const tid = t?.id ?? null;
// Track changed: close the prior open row. Always send play_ended
// with the actual position played; the server's skip rule decides
// whether to flag was_skipped.
if (tid !== prevTrackId && openPlayEventId) {
const id = openPlayEventId;
const dur = openLastPositionMs;
openPlayEventId = null;
openTrackId = null;
openLastPositionMs = 0;
api.post<EventOkResponse>('/api/events', {
type: 'play_ended',
play_event_id: id,
duration_played_ms: dur
}).catch(() => {});
}
// Entered playing for a new track (no open row yet for this track).
if (tid && s === 'playing' && openTrackId !== tid) {
void startNew(tid);
}
// Natural end: state went playing -> paused while at/past duration.
if (
prevState === 'playing' &&
s === 'paused' &&
openPlayEventId &&
player.duration > 0 &&
player.position >= player.duration
) {
const id = openPlayEventId;
const dur = Math.round(player.position * 1000);
openPlayEventId = null;
openTrackId = null;
openLastPositionMs = 0;
api.post<EventOkResponse>('/api/events', {
type: 'play_ended',
play_event_id: id,
duration_played_ms: dur
}).catch(() => {});
}
prevTrackId = tid;
prevState = s;
});
// Page close: sendBeacon a play_ended if an open play exists. The
// server's skip rule decides classification from the duration we
// actually played. Reads player.position directly rather than the
// tracked lastPositionMs — the open track is still current at
// pagehide time so the live read gives the freshest value, and the
// $effect-tracked path isn't reliably reached in test fixtures.
if (typeof window !== 'undefined') {
const onPageHide = () => {
if (!openPlayEventId) return;
const posMs = Math.round(player.position * 1000);
const payload = JSON.stringify({
type: 'play_ended',
play_event_id: openPlayEventId,
duration_played_ms: posMs
});
navigator.sendBeacon('/api/events', new Blob([payload], { type: 'application/json' }));
};
window.addEventListener('pagehide', onPageHide);
}
async function startNew(trackId: string): Promise<void> {
try {
const res = await api.post<PlayStartedResponse>('/api/events', {
type: 'play_started',
track_id: trackId,
client_id: clientId,
// Tag the play with the system playlist it came from
// (null for library / user-playlist / radio) so the server
// can advance that playlist's rotation.
source: player.queueSource ?? undefined,
// Device class for context conditioning. The web app is a
// browser session, so it reports 'web'.
device_class: 'web'
});
// The user may have moved on by the time the response arrives. Only
// adopt the id if we're still on the same track and still playing.
if (player.current?.id === trackId && player.state === 'playing') {
openPlayEventId = res.play_event_id;
openTrackId = trackId;
}
} catch {
// Best-effort; a missed event is acceptable.
}
}
}