Play podcast episodes in the web player

Episodes in the queue are no longer skipped. The player asks the
podcast API for the audio source and the resume position, plays the
publisher URL (or the same-origin proxy when the administrator enabled
it and the direct URL fails or is http:// on an https:// page) and
seeks before it starts, so it never reports a resumed episode that
plays from elsewhere: a server that cannot seek to the saved position
shows that and keeps the position until the user plays from the start.

Progress follows the contract: Play starts a listening session as an
explicit action above the handed-off generation, checkpoints go out
every 20 s and on pause, a seek is an explicit action, the end of the
stream completes the episode, and a stop, a page hide (beacon) or a
handoff saves the final position. Writes of a session run one after
another in the background; a superseded session stops writing, and a
device that loses the playback role ends its session without a report.
Reports always carry the position of their own episode.

Jam placeholders stay unplayable and episodes stay private for Jam
rules. A podcasts store holds the list, the podcast page and the
explicit episode actions for the UI of the next commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-20 15:12:38 +02:00
1 parent 2c551c5b71
commit 3ebfc45abb
4 files changed
+1566 -64

No files matched your search

+63 -49
View File
@@ -4,9 +4,11 @@ const {test} = require('node:test');
const vm = require('node:vm');
const template = readFileSync(`${__dirname}/../templates/player/scripts.html`, 'utf8');
// Queue items received from trusted devices that this player cannot play.
// Queue items received from trusted devices. Podcast episodes play through
// the podcast API (tests/player_podcasts.test.cjs); Jam placeholders and
// unresolved federated music never play here.
const podcast = {
id: -11, title: 'Episode 42', unavailable: true, stream_url: '',
id: -11, title: 'Episode 42', unavailable: false, stream_url: '',
source: {kind: 'podcast_episode', episode_id: 'ep1:x'},
wire_track: {id: 0, title: 'Episode 42', source: {kind: 'podcast_episode', episode_id: 'ep1:x'}},
};
@@ -26,42 +28,51 @@ function player(queue) {
const audio = {paused: false, src: 'old', pause() { this.paused = true; }, removeAttribute(name) { if (name === 'src') this.src = ''; }, load() {}};
const stores = {queue: Object.assign({syncCurrentIndexToTrack() {}}, queue)};
const context = vm.createContext({
audio, T: {queuePodcastUnplayable: 'Podcast · not playable', queuePrivateItem: 'Private item · hidden'},
audio, T: {queuePodcastItem: 'Podcast episode', queuePrivateItem: 'Private item · hidden'},
Alpine: {store: name => stores[name]},
});
vm.runInContext('this.methods = {' + methods + '};', context);
return Object.assign(context.methods, {audio, currentTrack: null, currentTime: 0, volume: 0.5, shuffle: false, repeatMode: 'off'});
}
test('podcast and private items are labelled and never played locally', () => {
test('episodes play here, placeholders never; both stay private in a Jam', () => {
const p = player({tracks: [], currentIndex: 0});
assert.equal(p._isUnplayableQueueItem(podcast), true);
assert.equal(p._isUnplayableQueueItem(podcast), false);
assert.equal(p._isPodcastEpisode(podcast), true);
assert.equal(p._isUnplayableQueueItem(privateItem), true);
assert.equal(p._isUnplayableQueueItem(remoteMusic), false);
assert.equal(p._isUnplayableQueueItem(song(1)), false);
assert.equal(p._unplayableQueueLabel(podcast), 'Podcast · not playable');
// Jam rules treat episodes and placeholders as private.
assert.equal(p._isPrivateQueueItem(podcast), true);
assert.equal(p._isPrivateQueueItem(privateItem), true);
assert.equal(p._isPrivateQueueItem(song(1)), false);
assert.equal(p._unplayableQueueLabel(podcast), '');
assert.equal(p._unplayableQueueLabel(privateItem), 'Private item · hidden');
assert.equal(p._unplayableQueueLabel(song(1)), '');
assert.equal(p._queueItemNote(podcast), 'Podcast episode');
assert.equal(p._queueItemNote(privateItem), 'Private item · hidden');
assert.equal(p._queueItemNote(song(1)), '');
// A browser item that only carries the verbatim wire item is recognised too.
assert.equal(p._isUnplayableQueueItem({id: -1, wire_track: podcast.wire_track}), true);
assert.equal(p._isPodcastEpisode({id: -1, wire_track: podcast.wire_track}), true);
assert.equal(p._isUnplayableQueueItem({id: -1, wire_track: privateItem.wire_track}), true);
});
test('skipping finds the next playable item in the direction of travel', () => {
const p = player({tracks: [], currentIndex: 0});
const tracks = [song(1), podcast, privateItem, song(2)];
assert.equal(p._playableQueueIndex(tracks, 1, 1), 3);
assert.equal(p._playableQueueIndex(tracks, 2, -1), 0);
assert.equal(p._playableQueueIndex([podcast], 0, 1), -1);
const tracks = [song(1), privateItem, podcast, privateItem, song(2)];
assert.equal(p._playableQueueIndex(tracks, 1, 1), 2);
assert.equal(p._playableQueueIndex(tracks, 3, 1), 4);
assert.equal(p._playableQueueIndex(tracks, 1, -1), 0);
assert.equal(p._playableQueueIndex([privateItem], 0, 1), -1);
});
test('showing an unplayable item stops and unloads the previous audio', () => {
const p = player({tracks: [podcast], currentIndex: 0});
const p = player({tracks: [privateItem], currentIndex: 0});
p.isPlaying = true;
p._showUnplayableQueueItem(podcast);
p._showUnplayableQueueItem(privateItem);
assert.equal(p.audio.paused, true);
assert.equal(p.audio.src, '');
assert.equal(p.isPlaying, false);
assert.equal(p.currentTrack, podcast);
assert.equal(p.currentTrack, privateItem);
assert.equal(p._historyTrack, null);
});
@@ -115,6 +126,7 @@ function activePlayer(queueTracks, currentIndex, audioState = {}, options = {})
'_showUnplayableQueueItem', '_syncLocalPlaybackState',
'_queueItemSourceKind', '_isUnplayableQueueItem', '_playableQueueIndex',
'_jamParticipantCommandAllowed', '_dropJamPlaceholders',
'_isPodcastEpisode', '_isPrivateQueueItem', '_episodeRef', '_endEpisode', '_reportEpisode',
];
const audio = Object.assign({
paused: true, currentTime: 0, duration: NaN, src: '',
@@ -155,16 +167,18 @@ function activePlayer(queueTracks, currentIndex, audioState = {}, options = {})
}
const episode = Object.assign({}, podcast, {duration_seconds: 1800});
// An item this player cannot play (a Jam placeholder) with a duration.
const placeholder = Object.assign({}, privateItem, {duration_seconds: 1800});
test('handoff of a podcast episode keeps its position for the next handoff', () => {
test('handoff of an unplayable item keeps its position for the next handoff', () => {
for (const audioTime of [95, 0]) {
// <audio> still holds a music track (95 s) or the page is fresh (0 s).
const p = activePlayer([song(1)], 0, {currentTime: audioTime, src: '/api/player/stream/1'});
p._executeRemoteCommand({command: 'transfer_state', payload: {
tracks: [song(1), episode], index: 1, track: episode,
tracks: [song(1), placeholder], index: 1, track: placeholder,
position_seconds: 1200, duration_seconds: 1800, paused: false,
}});
assert.equal(p.currentTrack, episode);
assert.equal(p.currentTrack, placeholder);
assert.equal(p.currentTime, 1200);
assert.equal(p.isPlaying, false);
assert.equal(p.audio.src, '', 'the previous track is unloaded');
@@ -184,35 +198,35 @@ test('library tracks still report the audio position', () => {
test('resume on an unplayable item skips it, also with repeat one', () => {
for (const repeatMode of ['one', 'off', 'all']) {
const p = activePlayer([podcast], 0);
const p = activePlayer([placeholder], 0);
p.repeatMode = repeatMode;
p.currentTime = 30;
p.resume();
p.next();
assert.equal(p.currentTrack, podcast);
assert.equal(p.currentTrack, placeholder);
assert.equal(p.isPlaying, false);
assert.equal(p.currentTime, 30, 'the item keeps its position');
assert.deepEqual(p.audio.played, []);
}
const p = activePlayer([song(1), podcast, song(2)], 1);
const p = activePlayer([song(1), placeholder, song(2)], 1);
p.repeatMode = 'one';
p.resume();
assert.equal(p.currentTrack.id, 2);
assert.deepEqual(p.audio.played, ['/api/player/stream/2']);
// Repeat all wraps around to the first playable item.
const wrap = activePlayer([song(1), podcast], 1);
const wrap = activePlayer([song(1), placeholder], 1);
wrap.repeatMode = 'all';
wrap.resume();
assert.equal(wrap.currentTrack.id, 1);
});
test('an episode reached without its position reports it as unknown, never as 0', () => {
// Next from the last music track lands on a trailing episode.
const p = activePlayer([song(1), episode], 0, {currentTime: 200, src: '/api/player/stream/1'});
test('an unplayable item reached without its position reports it as unknown, never as 0', () => {
// Next from the last music track lands on a trailing placeholder.
const p = activePlayer([song(1), placeholder], 0, {currentTime: 200, src: '/api/player/stream/1'});
p.isPlaying = true;
p.currentTime = 200;
p.next();
assert.equal(p.currentTrack, episode);
assert.equal(p.currentTrack, placeholder);
assert.equal(p.isPlaying, false);
let reported = p._devicePlaybackStatePayload();
assert.equal(reported.index, 1);
@@ -230,29 +244,29 @@ test('an episode reached without its position reports it as unknown, never as 0'
assert.equal(p.currentTrack.id, 1);
assert.equal(p._devicePlaybackStatePayload().position_unknown, undefined);
// Another browser or a Jam guest plays the episode row (position 0 sent).
const remote = activePlayer([song(1), episode], 0, {currentTime: 30, src: '/api/player/stream/1'});
// Another browser or a Jam guest plays the placeholder row (position 0 sent).
const remote = activePlayer([song(1), placeholder], 0, {currentTime: 30, src: '/api/player/stream/1'});
remote._executeRemoteCommand({command: 'play_from_index', payload: {
tracks: [song(1), episode], index: 1, track: episode, position_seconds: 0, paused: false,
tracks: [song(1), placeholder], index: 1, track: placeholder, position_seconds: 0, paused: false,
}});
assert.equal(remote.currentTrack, episode);
assert.equal(remote.currentTrack, placeholder);
assert.equal(remote._devicePlaybackStatePayload().position_unknown, true);
// A transfer passes on what the previous device did not know.
const relay = activePlayer([song(1)], 0);
relay._executeRemoteCommand({command: 'transfer_state', payload: {
tracks: [song(1), episode], index: 1, track: episode, position_seconds: 0,
tracks: [song(1), placeholder], index: 1, track: placeholder, position_seconds: 0,
position_unknown: true, paused: true,
}});
assert.equal(relay._devicePlaybackStatePayload().position_unknown, true);
// A mirrored state with a known position keeps it.
const mirror = activePlayer([song(1), episode], 0);
mirror._syncLocalPlaybackState({tracks: [song(1), episode], index: 1, track: episode, position_seconds: 900, paused: true});
const mirror = activePlayer([song(1), placeholder], 0);
mirror._syncLocalPlaybackState({tracks: [song(1), placeholder], index: 1, track: placeholder, position_seconds: 900, paused: true});
assert.equal(mirror._devicePlaybackStatePayload().position_seconds, 900);
assert.equal(mirror._devicePlaybackStatePayload().position_unknown, undefined);
});
test('repeat all and shuffle continue past a trailing unplayable item', () => {
const wrap = activePlayer([song(1), episode], 0, {currentTime: 200, src: '/api/player/stream/1'});
const wrap = activePlayer([song(1), placeholder], 0, {currentTime: 200, src: '/api/player/stream/1'});
wrap.repeatMode = 'all';
wrap.isPlaying = true;
wrap.next();
@@ -260,49 +274,49 @@ test('repeat all and shuffle continue past a trailing unplayable item', () => {
assert.equal(wrap.queue.currentIndex, 0);
assert.deepEqual(wrap.audio.played, ['/api/player/stream/1']);
// Shuffle picks the episode (index 1 of 3) and continues with music
// Shuffle picks the placeholder (index 1 of 3) and continues with music
// (searching towards the pick from the current item).
const shuffled = activePlayer([song(1), episode, song(2)], 2, {src: '/api/player/stream/2'}, {random: 0.5});
const shuffled = activePlayer([song(1), placeholder, song(2)], 2, {src: '/api/player/stream/2'}, {random: 0.5});
shuffled.shuffle = true;
shuffled.next();
assert.equal(shuffled.currentTrack.id, 1);
assert.equal(shuffled.isPlaying, false, 'the stub audio does not fire play events');
assert.deepEqual(shuffled.audio.played, ['/api/player/stream/1']);
// A trailing episode picked by shuffle wraps to the first playable item.
const trailing = activePlayer([song(1), song(2), episode], 1, {src: '/api/player/stream/2'}, {random: 0.9});
// A trailing placeholder picked by shuffle wraps to the first playable item.
const trailing = activePlayer([song(1), song(2), placeholder], 1, {src: '/api/player/stream/2'}, {random: 0.9});
trailing.shuffle = true;
trailing.next();
assert.equal(trailing.currentTrack.id, 1);
// Without repeat the queue ends on the episode, as before.
const stop = activePlayer([song(1), episode], 0, {src: '/api/player/stream/1'});
// Without repeat the queue ends on the placeholder, as before.
const stop = activePlayer([song(1), placeholder], 0, {src: '/api/player/stream/1'});
stop.next();
assert.equal(stop.currentTrack, episode);
assert.equal(stop.currentTrack, placeholder);
assert.equal(stop.isPlaying, false);
});
test('prev and seek work on a handed-off episode', () => {
test('prev and seek work on a handed-off unplayable item', () => {
const p = activePlayer([song(1), song(3)], 0, {currentTime: 95, src: '/api/player/stream/1'});
p._executeRemoteCommand({command: 'transfer_state', payload: {
tracks: [song(1), episode], index: 1, track: episode,
tracks: [song(1), placeholder], index: 1, track: placeholder,
position_seconds: 1200, duration_seconds: 1800, paused: false,
}});
// Seeking moves the episode's own position (nothing is loaded in <audio>).
// Seeking moves the placeholder's own position (nothing is loaded in <audio>).
p.seek(1500);
assert.equal(p.currentTime, 1500);
assert.equal(p._devicePlaybackStatePayload().position_seconds, 1500);
// Prev goes to the previous item instead of restarting the episode.
// Prev goes to the previous item instead of restarting the placeholder.
p.prev();
assert.equal(p.currentTrack.id, 1);
assert.deepEqual(p.audio.played, ['/api/player/stream/1']);
// At the start of the queue Prev leaves the episode and its position alone.
const first = activePlayer([episode, song(1)], 0);
// At the start of the queue Prev leaves the placeholder and its position alone.
const first = activePlayer([placeholder, song(1)], 0);
first._executeRemoteCommand({command: 'transfer_state', payload: {
tracks: [episode, song(1)], index: 0, track: episode, position_seconds: 1200, paused: true,
tracks: [placeholder, song(1)], index: 0, track: placeholder, position_seconds: 1200, paused: true,
}});
first.prev();
assert.equal(first.currentTrack, episode);
assert.equal(first.currentTrack, placeholder);
assert.equal(first.currentTime, 1200);
});