feat(core,web): player queue, play events and web player controller (M3, wip)
ci / mobile / mobile (Metro-бандл Android) (push) Successful in 1m6s
ci / ts / ts (packages + web) (push) Successful in 1m5s

- core: PlayQueue with shuffle and repeat, PlayAttempt counting only
  time actually played, EventBuffer with batching and backoff, uuidv7
- web: Player over HTMLAudioElement with Media Session, preload of the
  next track, expired-link refresh, local and server playback state,
  hotkeys; PlayerProvider is not wired into the shell yet
- ru/en strings and icons for the player and Collection

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
mrleo1nidandClaude Opus 5.5 committed 2026-10-20 07:28:20 +03:00
1 parent c05e523cbe
commit ec3c2810c8
10 files changed
+1025 -4

No files matched your search

+74
View File
@@ -0,0 +1,74 @@
import { createContext, useContext, useEffect, useState, useSyncExternalStore, type ReactNode } from 'react';
import { useSession } from '../app/session';
import { Player, type PlayerState } from './player';
const PlayerContext = createContext<Player | null>(null);
/** Плеер живёт, пока пользователь вошёл; горячие клавиши и сохранение при уходе со страницы. */
export function PlayerProvider({ children }: { children: ReactNode }) {
const session = useSession();
const [player] = useState(() => new Player(session));
useEffect(() => {
void player.restore().catch(() => undefined);
const onHide = () => player.onHide();
const onVisibility = () => document.visibilityState === 'hidden' && onHide();
window.addEventListener('pagehide', onHide);
document.addEventListener('visibilitychange', onVisibility);
const onKey = (e: KeyboardEvent) => handleHotkey(player, e);
document.addEventListener('keydown', onKey);
return () => {
window.removeEventListener('pagehide', onHide);
document.removeEventListener('visibilitychange', onVisibility);
document.removeEventListener('keydown', onKey);
player.dispose();
};
}, [player]);
return <PlayerContext.Provider value={player}>{children}</PlayerContext.Provider>;
}
/** Пробел — пауза, ←/→ — ±10 с, Shift+←/→ — трек, L — лайк (docs/web.md). */
export function handleHotkey(player: Player, e: KeyboardEvent) {
const target = e.target as HTMLElement | null;
if (target?.closest('input, textarea, select, [contenteditable="true"], [role="dialog"]')) return;
if (e.ctrlKey || e.metaKey || e.altKey) return;
const s = player.getState();
if (!s.track) return;
switch (e.key) {
case ' ':
if (target?.closest('button, a')) return; // пробел на кнопке нажимает её
e.preventDefault();
player.toggle();
break;
case 'ArrowLeft':
e.preventDefault();
if (e.shiftKey) player.prev();
else player.seek(s.positionMs - 10_000);
break;
case 'ArrowRight':
e.preventDefault();
if (e.shiftKey) player.next();
else player.seek(s.positionMs + 10_000);
break;
case 'l':
case 'L':
case 'д':
case 'Д':
e.preventDefault();
void player.react(s.track, s.track.reaction === 'like' ? null : 'like').catch(() => undefined);
break;
}
}
export function usePlayer(): Player {
const p = useContext(PlayerContext);
if (!p) throw new Error('usePlayer outside PlayerProvider');
return p;
}
export function usePlayerState(): PlayerState {
const p = usePlayer();
return useSyncExternalStore(p.subscribe, p.getState);
}
+526
View File
@@ -0,0 +1,526 @@
import {
EventBuffer,
PlayAttempt,
PlayQueue,
unwrap,
type AuthSession,
type PlayContext,
type RepeatMode,
type Track,
} from '@pipu/core';
export type { PlayContext, Track };
export interface PlayerState {
track: Track | null;
queue: Track[];
index: number;
context: PlayContext | null;
playing: boolean;
loading: boolean;
positionMs: number;
durationMs: number;
volume: number;
muted: boolean;
shuffle: boolean;
repeat: RepeatMode;
error: string | null;
}
const LOCAL_KEY = 'pipu.player';
const SAVE_EVERY_MS = 10_000;
const FLUSH_EVERY_MS = 30_000;
const PRELOAD_BEFORE_MS = 20_000;
/** Сохраняем не больше этого числа треков очереди (лимит сервера — 500). */
const MAX_SAVED_QUEUE = 500;
interface Saved {
queue: string[];
index: number;
positionMs: number;
context: PlayContext | null;
volume: number;
shuffle: boolean;
repeat: RepeatMode;
savedAt: string;
}
function deviceId(): string {
try {
let id = localStorage.getItem('pipu.device');
if (!id) {
id = crypto.randomUUID();
localStorage.setItem('pipu.device', id);
}
return id;
} catch {
return 'web';
}
}
/**
* Плеер веба. Логика очереди и учёта событий — из @pipu/core; здесь — адаптер к HTMLAudioElement,
* Media Session и сохранение «трек и момент» (локально и на сервере).
*/
export class Player {
private readonly audio: HTMLAudioElement;
private readonly queue = new PlayQueue();
private readonly events: EventBuffer;
private attempt: PlayAttempt | null = null;
private context: PlayContext | null = null;
private state: PlayerState;
private readonly listeners = new Set<() => void>();
private readonly device = deviceId();
private lastServerSave = 0;
private preloaded: string | null = null;
private refreshedFor: string | null = null;
private timers: ReturnType<typeof setInterval>[] = [];
constructor(
private readonly session: AuthSession,
audio?: HTMLAudioElement,
) {
this.audio = audio ?? new Audio();
this.audio.preload = 'auto';
this.events = new EventBuffer({
send: async (events) => {
unwrap(await this.session.client.POST('/api/v1/events', { body: { events } }));
},
});
this.state = {
track: null, queue: [], index: 0, context: null, playing: false, loading: false, positionMs: 0,
durationMs: 0, volume: 1, muted: false, shuffle: false, repeat: 'off', error: null,
};
this.bindAudio();
this.bindMediaSession();
this.timers.push(setInterval(() => void this.events.flush(), FLUSH_EVERY_MS));
}
// --- подписка (useSyncExternalStore) ---
subscribe = (fn: () => void) => {
this.listeners.add(fn);
return () => this.listeners.delete(fn);
};
getState = () => this.state;
private update(patch: Partial<PlayerState>) {
this.state = { ...this.state, ...patch };
for (const fn of this.listeners) fn();
}
private syncQueue() {
this.update({
track: this.queue.current ?? null,
queue: this.queue.tracks,
index: this.queue.index,
shuffle: this.queue.shuffle,
repeat: this.queue.repeat,
context: this.context,
});
}
// --- управление ---
/** Запустить список с позиции index в контексте (альбом, поиск, коллекция...). */
playList(tracks: Track[], index: number, context: PlayContext) {
const playable = tracks.filter((t) => t.available && t.stream_url);
const target = tracks[index];
if (!target || !playable.length) return;
this.finishAttempt('skip');
this.context = context;
this.queue.set(playable, Math.max(playable.indexOf(target), 0));
this.syncQueue();
void this.load(true);
}
toggle() {
if (this.state.playing) this.pause();
else this.play();
}
play() {
if (!this.queue.current) return;
if (!this.audio.src) {
void this.load(true, this.state.positionMs);
return;
}
void this.audio.play().catch(() => this.update({ playing: false }));
}
pause() {
this.audio.pause();
}
next() {
this.finishAttempt('skip');
if (this.queue.next()) {
this.syncQueue();
void this.load(true);
} else {
this.pause();
}
}
/** «Назад»: первые 3 с — к предыдущему треку, дальше — в начало текущего. */
prev() {
if (this.audio.currentTime > 3) {
this.seek(0);
return;
}
this.finishAttempt('skip');
if (this.queue.prev()) {
this.syncQueue();
void this.load(true);
}
}
jump(index: number) {
this.finishAttempt('skip');
this.queue.jump(index);
this.syncQueue();
void this.load(true);
}
seek(ms: number) {
const track = this.queue.current;
if (!track) return;
const to = Math.min(Math.max(ms, 0), track.duration_ms);
const from = Math.round(this.audio.currentTime * 1000);
this.attempt?.seek(to);
this.audio.currentTime = to / 1000;
this.update({ positionMs: to });
this.events.push({ type: 'seek', track_id: track.id, from_ms: from, position_ms: to });
this.saveSoon();
}
setVolume(v: number) {
this.audio.volume = Math.min(Math.max(v, 0), 1);
this.audio.muted = false;
this.update({ volume: this.audio.volume, muted: false });
this.saveLocal();
}
toggleMute() {
this.audio.muted = !this.audio.muted;
this.update({ muted: this.audio.muted });
}
toggleShuffle() {
this.queue.setShuffle(!this.queue.shuffle);
this.syncQueue();
this.saveLocal();
}
cycleRepeat() {
const order: RepeatMode[] = ['off', 'all', 'one'];
this.queue.repeat = order[(order.indexOf(this.queue.repeat) + 1) % order.length]!;
this.syncQueue();
this.saveLocal();
}
/** Лайк / дизлайк / снять реакцию. Дизлайк текущего трека сразу переключает на следующий. */
async react(track: Track, reaction: 'like' | 'dislike' | null) {
const prev = track.reaction;
const apply = (r: Track['reaction']) => {
for (const t of this.queue.tracks) if (t.id === track.id) t.reaction = r;
this.syncQueue();
};
apply(reaction);
const type = reaction ?? (prev === 'like' ? 'unlike' : 'undislike');
this.events.push({ type, track_id: track.id, position_ms: this.state.positionMs });
try {
const params = { params: { path: { id: track.id } } };
if (reaction) unwrap(await this.session.client.PUT('/api/v1/me/reactions/tracks/{id}', { ...params, body: { reaction } }));
else unwrap(await this.session.client.DELETE('/api/v1/me/reactions/tracks/{id}', params));
} catch (e) {
apply(prev);
throw e;
}
if (reaction === 'dislike' && this.queue.current?.id === track.id) this.next();
}
// --- загрузка трека ---
private async load(autoplay: boolean, startMs = 0) {
const track = this.queue.current;
if (!track?.stream_url) return;
this.update({ loading: true, error: null, positionMs: startMs, durationMs: track.duration_ms });
this.audio.src = track.stream_url;
if (startMs > 0) this.audio.currentTime = startMs / 1000;
this.attempt = new PlayAttempt(track, startMs);
this.preloaded = null;
this.events.push({
type: 'play_start',
track_id: track.id,
position_ms: startMs,
context_type: this.context?.type,
context_id: this.context?.id,
});
this.updateMediaMetadata(track);
this.saveServer();
if (autoplay) {
try {
await this.audio.play();
} catch {
// Автозапуск заблокирован браузером — ждём нажатия «Слушать».
this.update({ playing: false, loading: false });
}
}
}
/** Завершает текущую попытку: событие с реально прослушанным временем. */
private finishAttempt(type: 'play_end' | 'skip') {
const a = this.attempt;
if (!a) return;
this.attempt = null;
const pos = Math.round(this.audio.currentTime * 1000);
const kind = type === 'skip' ? a.outcome(pos) : 'play_end';
this.events.push({ type: kind, track_id: a.track.id, position_ms: pos, played_ms: Math.round(a.playedMs) });
void this.events.flush();
}
private bindAudio() {
const a = this.audio;
a.addEventListener('playing', () => {
this.update({ playing: true, loading: false });
if (this.attempt && this.state.positionMs > 0 && a.currentTime > 0.5) {
this.events.push({ type: 'resume', track_id: this.attempt.track.id, position_ms: this.state.positionMs });
}
});
a.addEventListener('pause', () => {
if (a.ended) return;
this.update({ playing: false });
const t = this.queue.current;
if (t) this.events.push({ type: 'pause', track_id: t.id, position_ms: this.state.positionMs });
this.saveServer();
});
a.addEventListener('waiting', () => this.update({ loading: true }));
a.addEventListener('timeupdate', () => {
const ms = Math.round(a.currentTime * 1000);
this.attempt?.tick(ms);
this.update({ positionMs: ms });
this.updatePositionState();
this.maybePreload(ms);
if (this.state.playing && Date.now() - this.lastServerSave > SAVE_EVERY_MS) this.saveServer();
this.saveLocal();
});
a.addEventListener('ended', () => {
this.finishAttempt('play_end');
if (this.queue.next(true)) {
this.syncQueue();
void this.load(true);
} else {
this.update({ playing: false, positionMs: 0 });
this.saveServer();
}
});
a.addEventListener('error', () => void this.onError());
a.addEventListener('volumechange', () => this.update({ volume: a.volume, muted: a.muted }));
}
/** Ссылка могла истечь (12 ч) — один раз берём свежую; иначе пропускаем трек. */
private async onError() {
const track = this.queue.current;
if (!track) return;
if (this.refreshedFor !== track.id) {
this.refreshedFor = track.id;
try {
const res = unwrap(await this.session.client.POST('/api/v1/tracks/batch', { body: { ids: [track.id] } }));
const fresh = res.items[0];
if (fresh?.stream_url) {
Object.assign(track, fresh);
void this.load(true, this.state.positionMs);
return;
}
} catch {
// упадём в пропуск ниже
}
}
this.update({ error: 'player.error', loading: false, playing: false });
this.attempt = null;
if (this.queue.peekNext() && this.queue.peekNext()!.id !== track.id) setTimeout(() => this.next(), 1500);
}
/** За 20 с до конца запрашиваем первый байт следующего трека — на сервере прогревается транскод. */
private maybePreload(ms: number) {
const cur = this.queue.current;
const next = this.queue.peekNext();
if (!cur || !next?.stream_url || this.preloaded === next.id) return;
if (cur.duration_ms - ms > PRELOAD_BEFORE_MS) return;
this.preloaded = next.id;
void fetch(next.stream_url, { headers: { Range: 'bytes=0-0' } }).catch(() => undefined);
}
// --- Media Session ---
private bindMediaSession() {
const ms = typeof navigator !== 'undefined' ? navigator.mediaSession : undefined;
if (!ms) return;
const set = (action: MediaSessionAction, fn: MediaSessionActionHandler) => {
try {
ms.setActionHandler(action, fn);
} catch {
// действие не поддерживается браузером
}
};
set('play', () => this.play());
set('pause', () => this.pause());
set('nexttrack', () => this.next());
set('previoustrack', () => this.prev());
set('seekbackward', (d) => this.seek(this.state.positionMs - (d.seekOffset ?? 10) * 1000));
set('seekforward', (d) => this.seek(this.state.positionMs + (d.seekOffset ?? 10) * 1000));
set('seekto', (d) => d.seekTime !== undefined && this.seek(d.seekTime * 1000));
}
private updateMediaMetadata(track: Track) {
if (typeof navigator === 'undefined' || !navigator.mediaSession || typeof MediaMetadata === 'undefined') return;
const cover = track.album.cover_url;
navigator.mediaSession.metadata = new MediaMetadata({
title: track.title,
artist: track.artists.map((a) => a.name).join(', '),
album: track.album.title,
artwork: cover
? [
{ src: `${cover}&size=300`, sizes: '300x300', type: 'image/webp' },
{ src: `${cover}&size=1200`, sizes: '1200x1200', type: 'image/webp' },
]
: [],
});
}
private updatePositionState() {
const ms = typeof navigator !== 'undefined' ? navigator.mediaSession : undefined;
const d = this.audio.duration;
if (!ms?.setPositionState || !Number.isFinite(d) || d <= 0) return;
try {
ms.setPositionState({ duration: d, position: Math.min(this.audio.currentTime, d), playbackRate: 1 });
} catch {
// некорректная позиция во время смены трека
}
}
// --- сохранение состояния ---
private snapshot(): Saved {
const ids = this.queue.tracks.map((t) => t.id);
const start = Math.max(0, Math.min(this.queue.index - Math.floor(MAX_SAVED_QUEUE / 2), ids.length - MAX_SAVED_QUEUE));
return {
queue: ids.slice(start, start + MAX_SAVED_QUEUE),
index: this.queue.index - start,
positionMs: this.state.positionMs,
context: this.context,
volume: this.state.volume,
shuffle: this.queue.shuffle,
repeat: this.queue.repeat,
savedAt: new Date().toISOString(),
};
}
private saveLocal() {
if (!this.queue.current) return;
try {
localStorage.setItem(LOCAL_KEY, JSON.stringify(this.snapshot()));
} catch {
// недоступное хранилище не мешает воспроизведению
}
}
private saveTimer: ReturnType<typeof setTimeout> | null = null;
private saveSoon() {
if (this.saveTimer) clearTimeout(this.saveTimer);
this.saveTimer = setTimeout(() => this.saveServer(), 1000);
}
/** PUT /me/playback-state; keepalive — запрос переживёт закрытие вкладки. */
saveServer(keepalive = false) {
const cur = this.queue.current;
if (!cur) return;
this.lastServerSave = Date.now();
this.saveLocal();
const s = this.snapshot();
void this.session.client
.PUT('/api/v1/me/playback-state', {
body: {
track_id: cur.id,
position_ms: s.positionMs,
queue: s.queue,
queue_index: s.index,
context: s.context ? { type: s.context.type, id: s.context.id, label: s.context.label } : undefined,
shuffle: s.shuffle,
repeat_mode: s.repeat,
volume: s.volume,
device_id: this.device,
},
keepalive,
})
.catch(() => undefined);
}
/** Уход со страницы: дослать события и состояние. */
onHide() {
this.saveServer(true);
void this.events.flush();
}
/**
* Восстановление после запуска: сначала локальная копия (мгновенно), затем серверная,
* если она новее и с другого устройства. Автозапуска нет — плеер на паузе в сохранённой позиции.
*/
async restore() {
let local: Saved | null = null;
try {
const raw = localStorage.getItem(LOCAL_KEY);
local = raw ? (JSON.parse(raw) as Saved) : null;
} catch {
local = null;
}
let saved = local;
try {
const server = unwrap(await this.session.client.GET('/api/v1/me/playback-state'));
if (
server.track_id &&
server.updated_at &&
(!local || (server.device_id !== this.device && server.updated_at > local.savedAt))
) {
saved = {
queue: server.queue,
index: server.queue_index,
positionMs: server.position_ms,
context: (server.context?.type ? server.context : null) as PlayContext | null,
volume: server.volume,
shuffle: server.shuffle,
repeat: server.repeat_mode,
savedAt: server.updated_at,
};
}
} catch {
// офлайн — остаёмся с локальной копией
}
if (!saved?.queue.length) return;
const res = unwrap(await this.session.client.POST('/api/v1/tracks/batch', { body: { ids: saved.queue } }));
const wanted = saved.queue[saved.index];
const tracks = res.items.filter((t) => t.available && t.stream_url);
if (!tracks.length) return;
const idx = Math.max(tracks.findIndex((t) => t.id === wanted), 0);
this.context = saved.context;
this.queue.repeat = saved.repeat;
this.queue.set(tracks, idx);
if (saved.shuffle) this.queue.setShuffle(true);
this.audio.volume = saved.volume;
const pos = tracks[idx]?.id === wanted ? saved.positionMs : 0;
this.syncQueue();
this.update({ positionMs: pos, durationMs: tracks[idx]!.duration_ms, volume: saved.volume });
this.updateMediaMetadata(tracks[idx]!);
}
dispose() {
this.finishAttempt('skip');
this.audio.pause();
this.audio.removeAttribute('src');
for (const t of this.timers) clearInterval(t);
void this.events.flush();
}
}
+14
View File
@@ -32,3 +32,17 @@ export { default as personIcon } from '@material-symbols/svg-400/rounded/person.
export { default as refreshIcon } from '@material-symbols/svg-400/rounded/refresh.svg';
export { default as storageIcon } from '@material-symbols/svg-400/rounded/hard_drive.svg';
export { default as storageFillIcon } from '@material-symbols/svg-400/rounded/hard_drive-fill.svg';
export { default as pauseIcon } from '@material-symbols/svg-400/rounded/pause-fill.svg';
export { default as nextIcon } from '@material-symbols/svg-400/rounded/skip_next-fill.svg';
export { default as prevIcon } from '@material-symbols/svg-400/rounded/skip_previous-fill.svg';
export { default as likeIcon } from '@material-symbols/svg-400/rounded/favorite.svg';
export { default as likeFillIcon } from '@material-symbols/svg-400/rounded/favorite-fill.svg';
export { default as dislikeIcon } from '@material-symbols/svg-400/rounded/heart_broken.svg';
export { default as dislikeFillIcon } from '@material-symbols/svg-400/rounded/heart_broken-fill.svg';
export { default as volumeIcon } from '@material-symbols/svg-400/rounded/volume_up.svg';
export { default as volumeOffIcon } from '@material-symbols/svg-400/rounded/volume_off.svg';
export { default as shuffleIcon } from '@material-symbols/svg-400/rounded/shuffle.svg';
export { default as repeatIcon } from '@material-symbols/svg-400/rounded/repeat.svg';
export { default as repeatOneIcon } from '@material-symbols/svg-400/rounded/repeat_one.svg';
export { default as historyIcon } from '@material-symbols/svg-400/rounded/history.svg';
export { default as historyFillIcon } from '@material-symbols/svg-400/rounded/history-fill.svg';