diff --git a/apps/mobile/app/(app)/player.tsx b/apps/mobile/app/(app)/player.tsx index b232c27..6d84a9b 100644 --- a/apps/mobile/app/(app)/player.tsx +++ b/apps/mobile/app/(app)/player.tsx @@ -1,5 +1,8 @@ import { useTabletLayout } from "@/hooks/use-tablet-layout" -import { TabletNowPlaying } from "@/components/tablet-now-playing" +import { + TabletNowPlaying, + type PlayerPanel, +} from "@/components/tablet-now-playing" import { atmosEnabled } from "@/lib/playback-capabilities" import { NavigationBar } from "expo-navigation-bar" import { MusicEntityView } from "@/components/music-entity-view" @@ -51,7 +54,9 @@ import { PlayerSymbol } from "@/components/player-symbol" import { useFavorites } from "@/contexts/favorites" import { usePlaybackActions, usePlaybackQueue } from "@/contexts/playback" import { useServerConfig } from "@/contexts/server-config" +import { LyricsView } from "@/components/lyrics-view" import { useCachedQuery } from "@/hooks/use-cached-query" +import { useLyrics } from "@/hooks/use-lyrics" import { useCoverPalette } from "@/hooks/use-cover-palette" import { useMediaMenuActions } from "@/hooks/use-media-menu-actions" import { useSystemVolume } from "@/hooks/use-system-volume" @@ -93,8 +98,14 @@ export default function PlayerScreen() { queueSongIds, } = usePlaybackQueue() const { setIsPlaying, skipNext, skipPrevious } = usePlaybackActions() - const { queue } = useLocalSearchParams<{ queue?: string }>() - const [showQueue, setShowQueue] = useState(queue === "1") + const params = useLocalSearchParams<{ queue?: string; lyrics?: string }>() + // The queue or lyrics, shown in place of the artwork. + const [panel, setPanel] = useState( + params.queue === "1" ? "queue" : params.lyrics === "1" ? "lyrics" : null + ) + const showQueue = panel === "queue" + const showLyrics = panel === "lyrics" + const lyrics = useLyrics(currentSong?.id ?? null) const [isDismissing, setIsDismissing] = useState(false) const [stageHeight, setStageHeight] = useState(0) const user = useCachedQuery(api.auth.currentUser) @@ -187,8 +198,8 @@ export default function PlayerScreen() { const handleGesture = useMemo(makeDismissGesture, [makeDismissGesture]) const controlsGesture = useMemo(makeDismissGesture, [makeDismissGesture]) const stageGesture = useMemo( - () => makeDismissGesture().enabled(!showQueue), - [makeDismissGesture, showQueue] + () => makeDismissGesture().enabled(panel === null), + [makeDismissGesture, panel] ) const hasCover = currentSong ? currentSong.album.cover != null : false @@ -243,9 +254,9 @@ export default function PlayerScreen() { setIsPlaying(!isPlaying) } - function toggleQueue() { + function togglePanel(next: PlayerPanel) { void Haptics.selectionAsync() - setShowQueue((value) => !value) + setPanel((value) => (value === next ? null : next)) } if (isTablet) { @@ -256,8 +267,9 @@ export default function PlayerScreen() { backgroundStyle={backgroundStyle} dismissStyle={dismissStyle} dismissGestures={{ handle: handleGesture, artwork: controlsGesture }} - showQueue={showQueue} - toggleQueue={toggleQueue} + panel={panel} + togglePanel={togglePanel} + lyrics={lyrics} metadata={songMeta} /> @@ -322,6 +334,20 @@ export default function PlayerScreen() { /> ) : null + ) : showLyrics ? ( + + {queueHeader} + + ) : ( togglePanel("lyrics")} + disabled={!lyrics && !showLyrics} + hitSlop={8} accessibilityRole="button" - accessibilityLabel="Lyrics" - accessibilityState={{ disabled: true }} - style={[styles.queueButton, styles.unavailable]} + accessibilityLabel={showLyrics ? "Hide lyrics" : "Show lyrics"} + accessibilityState={{ + selected: showLyrics, + disabled: !lyrics && !showLyrics, + }} + style={[ + styles.queueButton, + !lyrics && !showLyrics && styles.unavailable, + showLyrics && { backgroundColor: colors.selected }, + ]} > togglePanel("queue")} hitSlop={8} accessibilityRole="button" accessibilityLabel={showQueue ? "Hide queue" : "Show queue"} diff --git a/apps/mobile/components/lyrics-view.tsx b/apps/mobile/components/lyrics-view.tsx new file mode 100644 index 0000000..68176dc --- /dev/null +++ b/apps/mobile/components/lyrics-view.tsx @@ -0,0 +1,243 @@ +import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react" +import { + Pressable, + ScrollView, + StyleSheet, + Text, + View, + type ScrollViewInstance, +} from "react-native" + +import { + usePlaybackActions, + usePlaybackProgress, + usePlaybackQueue, +} from "@/contexts/playback" +import { useLyricsTime } from "@/hooks/use-lyrics" +import type { NowPlayingColors } from "@/lib/now-playing-colors" +import { + activeLineIndex, + type LyricLine, + type Lyrics, +} from "@otunes/convex/client/lyrics" + +/** How long a manual scroll keeps the view from following the song. */ +const MANUAL_SCROLL_HOLD_MS = 3000 +/** Where the playing line sits, as a share of the view's height from the top. */ +const ACTIVE_LINE_POSITION = 0.12 + +/** + * Lyrics in the player's own colors. Synced lines follow playback and seek + * when tapped; `null` lyrics show a short note instead. + */ +export function LyricsView({ + lyrics, + colors, + fontSize = 30, +}: { + lyrics: Lyrics | null | undefined + colors: NowPlayingColors + fontSize?: number +}) { + if (lyrics === undefined) return null + if (lyrics === null) { + return ( + + + No lyrics + + + ) + } + return +} + +function LyricsLines({ + lyrics, + colors, + fontSize, +}: { + lyrics: Lyrics + colors: NowPlayingColors + fontSize: number +}) { + const { currentTime } = usePlaybackProgress() + const { isPlaying } = usePlaybackQueue() + const { seekTo, setIsPlaying } = usePlaybackActions() + const time = useLyricsTime(lyrics, currentTime, isPlaying) + const active = activeLineIndex(lyrics, time) + const synced = lyrics.synced !== "none" + const scrollRef = useRef(null) + const lineOffsets = useRef([]) + const [height, setHeight] = useState(0) + const manualScrollAt = useRef(0) + + const scrollToLine = useCallback( + (index: number) => { + const y = lineOffsets.current[Math.max(index, 0)] + if (y === undefined || !synced || height === 0) return + if (Date.now() - manualScrollAt.current < MANUAL_SCROLL_HOLD_MS) return + scrollRef.current?.scrollTo({ + y: Math.max(0, y - height * ACTIVE_LINE_POSITION), + animated: true, + }) + }, + [height, synced] + ) + + useEffect(() => { + scrollToLine(active) + }, [active, scrollToLine]) + + const activeRef = useRef(active) + useEffect(() => { + activeRef.current = active + }, [active]) + const handleLineLayout = useCallback( + (index: number, y: number) => { + lineOffsets.current[index] = y + // Opening mid-song: jump once the playing line has been measured. + if (index === Math.max(activeRef.current, 0)) scrollToLine(index) + }, + [scrollToLine] + ) + + const playFrom = useCallback( + (seconds: number) => { + seekTo(seconds) + setIsPlaying(true) + manualScrollAt.current = 0 + }, + [seekTo, setIsPlaying] + ) + + const lineStyle = useMemo( + () => ({ fontSize, lineHeight: Math.round(fontSize * 1.18) }), + [fontSize] + ) + + return ( + setHeight(event.nativeEvent.layout.height)} + onScrollBeginDrag={() => { + manualScrollAt.current = Date.now() + }} + onMomentumScrollEnd={() => { + // Hold from when the scroll settles, not when the finger lifted. + if (manualScrollAt.current > 0) manualScrollAt.current = Date.now() + }} + > + {lyrics.lines.map((line, index) => + synced ? ( + + ) : ( + + {line.text} + + ) + )} + + ) +} + +/** + * One timed line. Only the playing line gets the time, so the others skip + * re-rendering as the song plays. + */ +const SyncedLine = memo(function SyncedLine({ + index, + line, + state, + time, + colors, + textStyle, + onSelect, + onLayoutY, +}: { + index: number + line: LyricLine + state: "past" | "active" | "next" + time: number | null + colors: NowPlayingColors + textStyle: { fontSize: number; lineHeight: number } + onSelect: (seconds: number) => void + onLayoutY: (index: number, y: number) => void +}) { + const active = state === "active" + return ( + onSelect(line.start ?? 0)} + onLayout={(event) => onLayoutY(index, event.nativeEvent.layout.y)} + accessibilityRole="button" + accessibilityHint="Plays from this line" + style={styles.line} + > + + {active && line.words + ? line.words.map((word, wordIndex) => ( + = word.start + ? colors.foreground + : colors.lyricsUnsung, + }} + > + {word.text} + + )) + : line.text} + + + ) +}) + +const styles = StyleSheet.create({ + fill: { flex: 1 }, + empty: { flex: 1, alignItems: "center", justifyContent: "center" }, + emptyText: { fontSize: 17, fontWeight: "600" }, + line: { paddingVertical: 9 }, + lineText: { fontWeight: "800" }, + plainLine: { fontWeight: "700", paddingVertical: 2 }, + stanzaGap: { height: 18 }, +}) diff --git a/apps/mobile/components/player.tsx b/apps/mobile/components/player.tsx index 0bbf8b6..03d3355 100644 --- a/apps/mobile/components/player.tsx +++ b/apps/mobile/components/player.tsx @@ -10,7 +10,7 @@ import { } from "@/contexts/downloads" import type { DownloadSource } from "@otunes/convex/client/download-queue" import { useServerConfig } from "@/contexts/server-config" -import type { BrowseSong } from "@otunes/convex/types" +import type { BrowseSong, SearchSong } from "@otunes/convex/types" import type { CoverPalette } from "@/lib/cover-palette" import { formatDuration } from "@/lib/format" import { albumCoverUrl } from "@/lib/urls" @@ -41,7 +41,8 @@ export const SongRow = memo(function SongRow({ swipe, downloadFrom, }: { - song: BrowseSong + /** Search results also show the lyrics line they matched. */ + song: SearchSong onPress?: () => void contextMenu?: Omit & { onAction: MediaMenuConfig["onAction"] @@ -87,6 +88,14 @@ export const SongRow = memo(function SongRow({ > {song.artist.name} · {song.album.title} + {song.lyricsSnippet ? ( + + Lyrics: “{song.lyricsSnippet}” + + ) : null} {downloaded || downloadState === "device" ? ( diff --git a/apps/mobile/components/playlist-search-bar.tsx b/apps/mobile/components/playlist-search-bar.tsx index 89d3db1..c57a3e6 100644 --- a/apps/mobile/components/playlist-search-bar.tsx +++ b/apps/mobile/components/playlist-search-bar.tsx @@ -2,16 +2,23 @@ import { useCallback, useMemo } from "react" import { Platform } from "react-native" import { Stack } from "expo-router" +import { useQuery } from "convex/react" + import { useDebouncedSearch } from "@/hooks/use-debounced-search" +import { api } from "@otunes/convex/_generated/api" import { useThemeColors } from "@/lib/theme" import { filterSongs } from "@otunes/convex/client/song-search" import type { BrowseSong } from "@otunes/convex/types" export function usePlaylistSearch(songs: BrowseSong[]) { const search = useDebouncedSearch() + const lyricsMatches = useQuery( + api.lyrics.matchingSongIds, + search.searchQuery.trim() ? { query: search.searchQuery } : "skip" + ) const filteredSongs = useMemo( - () => filterSongs(songs, search.searchQuery), - [songs, search.searchQuery] + () => filterSongs(songs, search.searchQuery, lyricsMatches), + [songs, search.searchQuery, lyricsMatches] ) return { ...search, filteredSongs } diff --git a/apps/mobile/components/search-results.tsx b/apps/mobile/components/search-results.tsx index 24fdcbb..9501421 100644 --- a/apps/mobile/components/search-results.tsx +++ b/apps/mobile/components/search-results.tsx @@ -16,7 +16,7 @@ import { usePlaybackActions } from "@/contexts/playback" import { useCachedQuery } from "@/hooks/use-cached-query" import { useMediaMenuActions } from "@/hooks/use-media-menu-actions" import { api } from "@otunes/convex/_generated/api" -import type { BrowseSong } from "@otunes/convex/types" +import type { BrowseSong, SearchSong } from "@otunes/convex/types" import { spacing, useThemeColors } from "@/lib/theme" function SearchResultsBody({ searchQuery }: { searchQuery: string }) { @@ -64,7 +64,7 @@ function SearchResultsBody({ searchQuery }: { searchQuery: string }) { [handleSongAction] ) const renderItem = useCallback( - ({ item: song }: ListRenderItemInfo) => ( + ({ item: song }: ListRenderItemInfo) => ( = 650 + const lyrics = useLyrics(roomy ? (currentSong?.id ?? null) : null) if (!focused || !config || !currentSong || queueSongIds.length === 0) return null @@ -166,16 +168,22 @@ export function TabletMiniPlayer() { {roomy ? ( + router.push({ + pathname: "/(app)/player", + params: { lyrics: "1" }, + }) + } accessibilityRole="button" - accessibilityLabel="Lyrics" - accessibilityState={{ disabled: true }} + accessibilityLabel="Show lyrics" + accessibilityState={{ disabled: !lyrics }} > ) : null} diff --git a/apps/mobile/components/tablet-now-playing.tsx b/apps/mobile/components/tablet-now-playing.tsx index 39ebaae..cce26cf 100644 --- a/apps/mobile/components/tablet-now-playing.tsx +++ b/apps/mobile/components/tablet-now-playing.tsx @@ -15,6 +15,7 @@ import { StatusBar } from "expo-status-bar" import { AudioOutputButton } from "@/components/audio-output-button" import { CoverImage } from "@/components/cover-image" +import { LyricsView } from "@/components/lyrics-view" import { NowPlayingQueue } from "@/components/now-playing-queue" import { PlayerProgress } from "@/components/player-progress" import { PlayerSlider } from "@/components/player-slider" @@ -24,6 +25,10 @@ import { useServerConfig } from "@/contexts/server-config" import { useSystemVolume } from "@/hooks/use-system-volume" import type { NowPlayingColors } from "@/lib/now-playing-colors" import { albumCoverUrl } from "@/lib/urls" +import type { Lyrics } from "@otunes/convex/client/lyrics" + +/** What the Now Playing screen shows beside or instead of the artwork. */ +export type PlayerPanel = "queue" | "lyrics" const queueMotion = { duration: 420, @@ -31,14 +36,18 @@ const queueMotion = { reduceMotion: ReduceMotion.System, } -/** Tablet player keeps transport controls visible while the queue opens beside them. */ +/** + * Tablet player keeps transport controls visible while the queue or lyrics + * open beside them. + */ export function TabletNowPlaying({ colors, backgroundStyle, dismissStyle, dismissGestures, - showQueue, - toggleQueue, + panel, + togglePanel, + lyrics, metadata, }: { colors: NowPlayingColors @@ -48,8 +57,9 @@ export function TabletNowPlaying({ handle: ReturnType artwork: ReturnType } - showQueue: boolean - toggleQueue: () => void + panel: PlayerPanel | null + togglePanel: (panel: PlayerPanel) => void + lyrics: Lyrics | null | undefined metadata: ReactNode }) { const router = useRouter() @@ -63,7 +73,9 @@ export function TabletNowPlaying({ const { volume, setVolume, available: volumeAvailable } = useSystemVolume() const [queueHeight, setQueueHeight] = useState(0) const wideLayout = width >= 700 - const sideBySide = showQueue && wideLayout + const showQueue = panel === "queue" + const showLyrics = panel === "lyrics" + const sideBySide = panel !== null && wideLayout const progress = useSharedValue(sideBySide ? 1 : 0) useEffect(() => { progress.value = withTiming(sideBySide ? 1 : 0, queueMotion) @@ -124,7 +136,14 @@ export function TabletNowPlaying({ /> ) - const queue = ( + const panelContent = showLyrics ? ( + + ) : ( {wideLayout ? ( setQueueHeight(event.nativeEvent.layout.height) } > - {queueHeight > 0 ? queue : null} + {queueHeight > 0 ? panelContent : null} ) : null} - {showQueue && !sideBySide ? ( + {panel && !sideBySide ? ( - {queueHeight > 0 ? queue : null} + {queueHeight > 0 ? panelContent : null} ) : null} @@ -280,21 +297,29 @@ export function TabletNowPlaying({ /> togglePanel("lyrics")} + disabled={!lyrics && !showLyrics} accessibilityRole="button" - accessibilityLabel="Lyrics" - accessibilityState={{ disabled: true }} - style={[styles.footerButton, { opacity: 0.4 }]} + accessibilityLabel={showLyrics ? "Hide lyrics" : "Show lyrics"} + accessibilityState={{ + selected: showLyrics, + disabled: !lyrics && !showLyrics, + }} + style={[ + styles.footerButton, + !lyrics && !showLyrics && { opacity: 0.4 }, + showLyrics && { backgroundColor: colors.selected }, + ]} > togglePanel("queue")} accessibilityRole="button" accessibilityLabel={showQueue ? "Hide queue" : "Show queue"} accessibilityState={{ selected: showQueue }} diff --git a/apps/mobile/hooks/use-lyrics.ts b/apps/mobile/hooks/use-lyrics.ts new file mode 100644 index 0000000..bd27a41 --- /dev/null +++ b/apps/mobile/hooks/use-lyrics.ts @@ -0,0 +1,109 @@ +import { File } from "expo-file-system" +import { useEffect, useMemo, useState, useSyncExternalStore } from "react" + +import { api } from "@otunes/convex/_generated/api" +import type { Id } from "@otunes/convex/_generated/dataModel" +import { + followLyrics, + parseLyrics, + type Lyrics, +} from "@otunes/convex/client/lyrics" +import { readLyricsTag } from "@otunes/convex/client/lyrics-tags" +import { useDownloads } from "@/contexts/downloads" +import { useServerConfig } from "@/contexts/server-config" +import { useCachedQuery } from "@/hooks/use-cached-query" +import { downloadedAudioUri } from "@/lib/downloads" + +// Lyrics read from downloaded files, by file. Files do not change once saved. +const localLyrics = new Map>() + +async function readFileLyrics(uri: string) { + const handle = new File(uri).open() + try { + const text = await readLyricsTag({ + size: handle.size ?? 0, + read: (offset, length) => { + handle.offset = offset + return handle.readBytes(length) + }, + }) + return text?.trim() || null + } finally { + handle.close() + } +} + +function readLocalLyrics(uri: string) { + let lyrics = localLyrics.get(uri) + if (!lyrics) { + lyrics = readFileLyrics(uri).catch(() => null) + localLyrics.set(uri, lyrics) + } + return lyrics +} + +const noopSubscribe = () => () => {} + +/** + * A song's lyrics: from its downloaded file when there is one, otherwise from + * the server. `undefined` while loading, `null` when the song has none. + */ +export function useLyrics(songId: Id<"songs"> | null) { + const { config } = useServerConfig() + const { queue } = useDownloads() + const fileUri = useSyncExternalStore(queue?.subscribe ?? noopSubscribe, () => + songId && config && queue?.getDownloaded(songId) + ? downloadedAudioUri(config, songId) + : null + ) + const [local, setLocal] = useState<{ uri: string; text: string | null }>() + + useEffect(() => { + if (!fileUri) return + let current = true + void readLocalLyrics(fileUri).then((text) => { + if (current) setLocal({ uri: fileUri, text }) + }) + return () => { + current = false + } + }, [fileUri]) + + const localText = fileUri && local?.uri === fileUri ? local.text : undefined + // Songs without a downloaded copy, or whose copy has no lyrics tag. + const remote = useCachedQuery( + api.lyrics.forSong, + songId && (!fileUri || localText === null) ? { id: songId } : "skip" + ) + const text = localText || remote + + return useMemo(() => { + if (!songId) return null + if (text === undefined) return undefined + return text ? parseLyrics(text) : null + }, [songId, text]) +} + +/** + * The playback time for highlighting lyrics: the player's `currentTime`, + * advanced by `followLyrics` between its progress updates. + */ +export function useLyricsTime( + lyrics: Lyrics | null | undefined, + currentTime: number, + isPlaying: boolean +) { + // Time reached since the player last reported `from`. + const [advanced, setAdvanced] = useState<{ from: number; time: number }>() + + useEffect(() => { + if (!lyrics || !isPlaying) return + return followLyrics(lyrics, currentTime, (time) => + setAdvanced({ from: currentTime, time }) + ) + }, [lyrics, currentTime, isPlaying]) + + return isPlaying && advanced?.from === currentTime + ? advanced.time + : currentTime +} diff --git a/apps/mobile/lib/now-playing-colors.ts b/apps/mobile/lib/now-playing-colors.ts index 13ef5ed..c898293 100644 --- a/apps/mobile/lib/now-playing-colors.ts +++ b/apps/mobile/lib/now-playing-colors.ts @@ -12,6 +12,10 @@ export type NowPlayingColors = { selected: string selectedForeground: string highlight: string + /** Lyrics lines other than the one playing. */ + lyricsInactive: string + /** Words of the playing line not yet sung. */ + lyricsUnsung: string isDark: boolean } @@ -28,6 +32,8 @@ export function nowPlayingColors(palette: CoverPalette): NowPlayingColors { selected: withAlpha(foreground, 0.8), selectedForeground: palette.background, highlight: withAlpha(foreground, 0.1), + lyricsInactive: withAlpha(foreground, 0.35), + lyricsUnsung: withAlpha(foreground, 0.55), isDark: palette.isDark, } } diff --git a/apps/web/app/api/song/[id]/download/route.ts b/apps/web/app/api/song/[id]/download/route.ts index 73b78c4..d57d0d0 100644 --- a/apps/web/app/api/song/[id]/download/route.ts +++ b/apps/web/app/api/song/[id]/download/route.ts @@ -7,7 +7,7 @@ import { audioInfo } from "@/lib/server-audio-info" import { streamFile } from "@/lib/server-audio-stream" import { spawnFfmpeg } from "@/lib/server-ffmpeg" import { seekableLosslessFile } from "@/lib/server-lossless" -import { getSongSource } from "@/lib/server-song" +import { getSongLyrics, getSongSource } from "@/lib/server-song" import { NextRequest, NextResponse, userAgent } from "next/server" import fs from "node:fs/promises" import os from "node:os" @@ -40,9 +40,14 @@ async function fileResponse(songId: string, file: string, contentType: string) { }) } +/** Longest lyrics passed to ffmpeg; Linux caps one argument at 128 KiB. */ +const MAX_LYRICS_ARGUMENT_BYTES = 100 * 1024 + /** * Transcodes to an AAC .m4a with its index up front, so the saved file has a - * duration and seeks offline. The temporary file is removed once sent. + * duration and seeks offline. Tags carry over, and the stored lyrics are + * written too, since ffmpeg drops some formats' lyrics tags (like MP3 USLT) + * when writing MP4. The temporary file is removed once sent. */ async function transcodeResponse( songId: string, @@ -50,6 +55,11 @@ async function transcodeResponse( kbps: number, signal: AbortSignal ) { + const lyrics = await getSongLyrics(songId) + const lyricsArgs = + lyrics && Buffer.byteLength(lyrics) <= MAX_LYRICS_ARGUMENT_BYTES + ? ["-metadata", `lyrics=${lyrics}`] + : [] const dir = await fs.mkdtemp(path.join(os.tmpdir(), "otunes-download-")) const output = path.join(dir, "audio.m4a") const cleanup = () => fs.rm(dir, { recursive: true, force: true }) @@ -64,6 +74,7 @@ async function transcodeResponse( "aac", "-b:a", `${kbps}k`, + ...lyricsArgs, "-movflags", "+faststart", output, diff --git a/apps/web/components/lazy-queue-panel.tsx b/apps/web/components/lazy-queue-panel.tsx index b7a38d9..327fb27 100644 --- a/apps/web/components/lazy-queue-panel.tsx +++ b/apps/web/components/lazy-queue-panel.tsx @@ -8,8 +8,14 @@ const QueuePanel = dynamic(() => import("@/components/queue-panel").then((module) => module.QueuePanel) ) -export function LazyQueuePanel() { - const { queueOpen } = usePlayback() +const LyricsPanel = dynamic(() => + import("@/components/lyrics-panel").then((module) => module.LyricsPanel) +) +/** The queue or lyrics panel beside the page, whichever is open. */ +export function LazyQueuePanel() { + const { queueOpen, lyricsOpen } = usePlayback() + + if (lyricsOpen) return return queueOpen ? : null } diff --git a/apps/web/components/lyrics-panel.tsx b/apps/web/components/lyrics-panel.tsx new file mode 100644 index 0000000..a3b3520 --- /dev/null +++ b/apps/web/components/lyrics-panel.tsx @@ -0,0 +1,164 @@ +"use client" + +import * as React from "react" + +import { + useIsPlaying, + usePlayback, + usePlaybackProgress, +} from "@/components/playback-provider" +import { useLyrics, useLyricsTime } from "@/hooks/use-lyrics" +import { cn } from "@/lib/utils" +import { + activeLineIndex, + type LyricLine, + type Lyrics, +} from "@otunes/convex/client/lyrics" + +/** How long a manual scroll keeps the panel from following the song. */ +const MANUAL_SCROLL_HOLD_MS = 3000 + +/** Lyrics beside the page, in the queue's place. Synced lines follow playback. */ +export function LyricsPanel() { + const { currentSong } = usePlayback() + const lyrics = useLyrics(currentSong?.id ?? null) + + return ( + + ) +} + +function LyricsLines({ lyrics }: { lyrics: Lyrics }) { + const { seekTo, currentTime } = usePlaybackProgress() + const isPlaying = useIsPlaying() + const { setIsPlaying } = usePlayback() + const time = useLyricsTime(lyrics, currentTime, isPlaying) + const active = activeLineIndex(lyrics, time) + const scrollRef = React.useRef(null) + const manualScrollAt = React.useRef(0) + const synced = lyrics.synced !== "none" + + React.useEffect(() => { + const container = scrollRef.current + const line = container?.querySelector( + `[data-line="${Math.max(active, 0)}"]` + ) + if ( + !container || + !line || + !synced || + Date.now() - manualScrollAt.current < MANUAL_SCROLL_HOLD_MS + ) { + return + } + container.scrollTo({ + top: line.offsetTop - container.clientHeight * 0.25, + behavior: "smooth", + }) + }, [active, synced]) + + const playFrom = React.useCallback( + (seconds: number) => { + seekTo(seconds) + setIsPlaying(true) + }, + [seekTo, setIsPlaying] + ) + + const holdScroll = () => { + manualScrollAt.current = Date.now() + } + + return ( +
+ {lyrics.lines.map((line, index) => + synced ? ( + + ) : ( +

+ {line.text} +

+ ) + )} +
+ ) +} + +/** + * One timed line. Only the active line gets the playback time, so memoized + * lines elsewhere skip re-rendering as the song plays. + */ +const SyncedLine = React.memo(function SyncedLine({ + index, + line, + state, + time, + onSelect, +}: { + index: number + line: LyricLine + state: "past" | "active" | "next" + time: number | null + onSelect: (seconds: number) => void +}) { + const active = state === "active" + return ( + + ) +}) diff --git a/apps/web/components/playback-provider.tsx b/apps/web/components/playback-provider.tsx index 7849447..c1cbe71 100644 --- a/apps/web/components/playback-provider.tsx +++ b/apps/web/components/playback-provider.tsx @@ -60,10 +60,13 @@ type PlaybackContextValue = { shuffleEnabled: boolean repeatEnabled: RepeatMode queueOpen: boolean + /** The lyrics panel, which shares the queue's place beside the page. */ + lyricsOpen: boolean isPlaying: boolean volume: number setQueueOpen: (open: boolean) => void toggleQueueOpen: () => void + toggleLyricsOpen: () => void setIsPlaying: (playing: boolean) => void setVolume: (volume: number) => void /** An origin from `downloadsQueueOrigin` plays downloads in any quality. */ @@ -122,6 +125,7 @@ type PlaybackActions = Omit< | "shuffleEnabled" | "repeatEnabled" | "queueOpen" + | "lyricsOpen" | "isPlaying" | "volume" | "dolbyAtmosSupported" @@ -506,7 +510,12 @@ export function PlaybackProvider({ children }: { children: ReactNode }) { const currentTimeRef = useRef(0) const durationRef = useRef(0) - const [queueOpen, setQueueOpen] = useState(false) + const [sidePanel, setSidePanel] = useState<"queue" | "lyrics" | null>(null) + const queueOpen = sidePanel === "queue" + const lyricsOpen = sidePanel === "lyrics" + const setQueueOpen = useCallback((open: boolean) => { + setSidePanel((panel) => (open ? "queue" : panel === "queue" ? null : panel)) + }, []) const [isPlaying, setIsPlaying] = useState(false) const [playbackStartVersion, setPlaybackStartVersion] = useState(0) const [currentTime, setCurrentTime] = useState(0) @@ -1441,7 +1450,11 @@ export function PlaybackProvider({ children }: { children: ReactNode }) { ) const toggleQueueOpen = useCallback(() => { - setQueueOpen((open) => !open) + setSidePanel((panel) => (panel === "queue" ? null : "queue")) + }, []) + + const toggleLyricsOpen = useCallback(() => { + setSidePanel((panel) => (panel === "lyrics" ? null : "lyrics")) }, []) const toggleShuffle = useCallback(async () => { @@ -1547,6 +1560,7 @@ export function PlaybackProvider({ children }: { children: ReactNode }) { () => ({ setQueueOpen, toggleQueueOpen, + toggleLyricsOpen, setIsPlaying, setVolume, playInOrder, @@ -1572,7 +1586,9 @@ export function PlaybackProvider({ children }: { children: ReactNode }) { skipPrevious, }), [ + setQueueOpen, toggleQueueOpen, + toggleLyricsOpen, setVolume, playInOrder, playShuffled, @@ -1608,6 +1624,7 @@ export function PlaybackProvider({ children }: { children: ReactNode }) { shuffleEnabled: playback.shuffleEnabled, repeatEnabled: playback.repeatEnabled, queueOpen, + lyricsOpen, isPlaying: isPlaybackActive, volume, dolbyAtmosSupported, @@ -1618,6 +1635,7 @@ export function PlaybackProvider({ children }: { children: ReactNode }) { currentSong, currentFormat, queueOpen, + lyricsOpen, isPlaybackActive, volume, dolbyAtmosSupported, diff --git a/apps/web/components/player-bar.tsx b/apps/web/components/player-bar.tsx index 720f459..764bca0 100644 --- a/apps/web/components/player-bar.tsx +++ b/apps/web/components/player-bar.tsx @@ -29,6 +29,7 @@ import { import { Button } from "@/components/ui/button" import { Slider } from "@/components/ui/slider" import { useSidebar } from "@/components/ui/sidebar" +import { useLyrics } from "@/hooks/use-lyrics" import { albumCoverUrl } from "@/lib/cover-urls" import { cn } from "@/lib/utils" import { formatDuration } from "@/lib/format-duration" @@ -73,18 +74,21 @@ export function PlayerBar() { shuffleEnabled, repeatEnabled, queueOpen, + lyricsOpen, isPlaying, volume, queueSongIds, setIsPlaying, setVolume, toggleQueueOpen, + toggleLyricsOpen, toggleShuffle, cycleRepeat, skipNext, skipPrevious, } = usePlayback() const { state, isMobile } = useSidebar() + const lyrics = useLyrics(currentSong?.id ?? null) const hasQueue = queueSongIds.length > 0 const sidebarExpanded = !isMobile && state === "expanded" @@ -94,7 +98,7 @@ export function PlayerBar() { className={cn( "@container pointer-events-none fixed bottom-4 z-50 flex justify-center px-4 transition-[left,right] duration-200 ease-linear", sidebarExpanded ? "right-0 left-[16rem]" : "inset-x-0", - queueOpen && !isMobile && "right-72" + (queueOpen || lyricsOpen) && !isMobile && "right-72" )} >
@@ -227,9 +231,14 @@ export function PlayerBar() { diff --git a/apps/web/components/playlist-view.tsx b/apps/web/components/playlist-view.tsx index 0630d7a..857bd49 100644 --- a/apps/web/components/playlist-view.tsx +++ b/apps/web/components/playlist-view.tsx @@ -5,7 +5,7 @@ import { stationArtistId } from "@/lib/station-artist" import * as React from "react" import Image from "next/image" import { useRouter } from "next/navigation" -import { useMutation } from "convex/react" +import { useMutation, useQuery } from "convex/react" import { ImageIcon, Pencil, @@ -101,9 +101,13 @@ export function PlaylistView({ playlist }: { playlist: BrowsePlaylistDetail }) { : playlistSongs const [searchQuery, setSearchQuery] = React.useState("") const isSearching = searchQuery.trim() !== "" + const lyricsMatches = useQuery( + api.lyrics.matchingSongIds, + isSearching ? { query: searchQuery } : "skip" + ) const filteredSongs = React.useMemo( - () => filterSongs(songs, searchQuery), - [songs, searchQuery] + () => filterSongs(songs, searchQuery, lyricsMatches), + [songs, searchQuery, lyricsMatches] ) const playlistSongIds = React.useMemo( () => songs.map((song) => song.id as Id<"songs">), diff --git a/apps/web/components/search-song-item.tsx b/apps/web/components/search-song-item.tsx index 3276d5f..94100c1 100644 --- a/apps/web/components/search-song-item.tsx +++ b/apps/web/components/search-song-item.tsx @@ -14,10 +14,10 @@ import { type MediaContextMenuProps, } from "@/components/media-context-menu" import type { Id } from "@otunes/convex/_generated/dataModel" -import type { BrowseSong } from "@otunes/convex/types" +import type { SearchSong } from "@otunes/convex/types" import { albumCoverUrl } from "@/lib/cover-urls" -export function SearchSongItem({ song }: { song: BrowseSong }) { +export function SearchSongItem({ song }: { song: SearchSong }) { const { openAddToPlaylist } = useAddToPlaylist() const { isSongFavorite, toggleSongFavorite } = useFavorites() const { runQueueAction, createStation } = useQueueMediaActions() @@ -103,6 +103,11 @@ export function SearchSongItem({ song }: { song: BrowseSong }) { >

{song.artist.name}

+ {song.lyricsSnippet ? ( +

+ Lyrics: “{song.lyricsSnippet}” +

+ ) : null}
diff --git a/apps/web/hooks/use-lyrics.ts b/apps/web/hooks/use-lyrics.ts new file mode 100644 index 0000000..061287f --- /dev/null +++ b/apps/web/hooks/use-lyrics.ts @@ -0,0 +1,105 @@ +"use client" + +import { useEffect, useMemo, useState, useSyncExternalStore } from "react" + +import { api } from "@otunes/convex/_generated/api" +import type { Id } from "@otunes/convex/_generated/dataModel" +import { + followLyrics, + parseLyrics, + type Lyrics, +} from "@otunes/convex/client/lyrics" +import { readLyricsTag } from "@otunes/convex/client/lyrics-tags" +import { useCachedQuery } from "@/hooks/use-cached-query" +import { downloadedAudioBlob, downloadQueue } from "@/lib/downloads" + +// Lyrics read from downloaded files, by song. Files do not change once saved. +const localLyrics = new Map>() + +function readLocalLyrics(songId: string) { + let lyrics = localLyrics.get(songId) + if (!lyrics) { + lyrics = downloadedAudioBlob(songId) + .then((blob) => + blob + ? readLyricsTag({ + size: blob.size, + read: async (offset, length) => + new Uint8Array( + await blob.slice(offset, offset + length).arrayBuffer() + ), + }) + : null + ) + .then((text) => text?.trim() || null) + .catch(() => null) + localLyrics.set(songId, lyrics) + } + return lyrics +} + +/** + * A song's lyrics: from its downloaded file when there is one, otherwise from + * the server. `undefined` while loading, `null` when the song has none. + */ +export function useLyrics(songId: Id<"songs"> | null) { + const downloaded = useSyncExternalStore( + downloadQueue.subscribe, + () => (songId ? downloadQueue.getDownloaded(songId) !== undefined : false), + () => false + ) + const [local, setLocal] = useState<{ + songId: string + text: string | null + } | null>(null) + + useEffect(() => { + if (!songId || !downloaded) return + let current = true + void readLocalLyrics(songId).then((text) => { + if (current) setLocal({ songId, text }) + }) + return () => { + current = false + } + }, [songId, downloaded]) + + const localText = + songId && downloaded && local?.songId === songId ? local.text : undefined + // Songs without a downloaded copy, or whose copy has no lyrics tag. + const remote = useCachedQuery( + api.lyrics.forSong, + songId && (!downloaded || localText === null) ? { id: songId } : "skip" + ) + const text = localText || remote + + return useMemo(() => { + if (!songId) return null + if (text === undefined) return undefined + return text ? parseLyrics(text) : null + }, [songId, text]) +} + +/** + * The playback time for highlighting lyrics: the player's `currentTime`, + * advanced by `followLyrics` between its progress updates. + */ +export function useLyricsTime( + lyrics: Lyrics | null | undefined, + currentTime: number, + isPlaying: boolean +) { + // Time reached since the player last reported `from`. + const [advanced, setAdvanced] = useState<{ from: number; time: number }>() + + useEffect(() => { + if (!lyrics || !isPlaying) return + return followLyrics(lyrics, currentTime, (time) => + setAdvanced({ from: currentTime, time }) + ) + }, [lyrics, currentTime, isPlaying]) + + return isPlaying && advanced?.from === currentTime + ? advanced.time + : currentTime +} diff --git a/apps/web/lib/downloads.ts b/apps/web/lib/downloads.ts index caa18dc..06c6c99 100644 --- a/apps/web/lib/downloads.ts +++ b/apps/web/lib/downloads.ts @@ -204,11 +204,7 @@ export async function downloadedAudioUrl(songId: string) { audioUrls.set(songId, existing) return existing } - const db = await openDatabase() - const blob = await readRequest( - db.transaction(AUDIO_STORE).objectStore(AUDIO_STORE), - songId - ) + const blob = await downloadedAudioBlob(songId) if (!blob) return null const url = URL.createObjectURL(blob) audioUrls.set(songId, url) @@ -218,6 +214,16 @@ export async function downloadedAudioUrl(songId: string) { return url } +/** A downloaded song's audio file, or null when it is not downloaded. */ +export async function downloadedAudioBlob(songId: string) { + const db = await openDatabase() + const blob = await readRequest( + db.transaction(AUDIO_STORE).objectStore(AUDIO_STORE), + songId + ) + return blob ?? null +} + export function readRememberedDownloadQuality() { try { return parseDownloadQuality(localStorage.getItem(REMEMBERED_QUALITY_KEY)) diff --git a/apps/web/lib/server-song.ts b/apps/web/lib/server-song.ts index 1ffe84d..1a2bc8b 100644 --- a/apps/web/lib/server-song.ts +++ b/apps/web/lib/server-song.ts @@ -22,6 +22,16 @@ export async function getSongSource(id: string): Promise { return song } +/** The song's stored lyrics tag, or null without lyrics. */ +export async function getSongLyrics(id: string): Promise { + const token = await convexAuthNextjsToken() + return await fetchQuery( + api.lyrics.forSong, + { id: id as Id<"songs"> }, + convexServerOptions(token) + ) +} + const SOURCE_BATCH_SIZE = 200 /** `getSongSource` for many songs, in batches. Missing songs are left out. */ diff --git a/packages/convex/client/lyrics-tags.ts b/packages/convex/client/lyrics-tags.ts new file mode 100644 index 0000000..1543f1f --- /dev/null +++ b/packages/convex/client/lyrics-tags.ts @@ -0,0 +1,214 @@ +/** + * Reads the lyrics tag from a downloaded audio file, so offline playback shows + * the same lyrics the server has. Downloads are MP4 (`©lyr`), FLAC (`LYRICS` + * Vorbis comment) or MP3 (ID3 `USLT`), and only the tag bytes are read. + */ + +export type ByteReader = { + size: number + read: (offset: number, length: number) => Promise +} + +const utf8 = new TextDecoder("utf-8") + +function ascii(bytes: Uint8Array, start: number, length: number) { + let text = "" + for (let i = start; i < Math.min(start + length, bytes.length); i++) { + text += String.fromCharCode(bytes[i]) + } + return text +} + +function view(bytes: Uint8Array) { + return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength) +} + +/** Most bytes read for a tag, so a corrupt length cannot load a whole file. */ +const MAX_TAG_BYTES = 16 * 1024 * 1024 + +type Box = { type: string; start: number; size: number; header: number } + +/** The boxes inside `bytes[start, end)`. */ +function* boxes(bytes: Uint8Array, start: number, end: number) { + const data = view(bytes) + let offset = start + while (offset + 8 <= end) { + let size = data.getUint32(offset) + let header = 8 + if (size === 1 && offset + 16 <= end) { + size = Number(data.getBigUint64(offset + 8)) + header = 16 + } else if (size === 0) { + size = end - offset + } + if (size < header) return + yield { type: ascii(bytes, offset + 4, 4), start: offset, size, header } + offset += size + } +} + +function child(bytes: Uint8Array, parent: Box, type: string, skip = 0) { + for (const box of boxes( + bytes, + parent.start + parent.header + skip, + parent.start + parent.size + )) { + if (box.type === type) return box + } + return undefined +} + +async function mp4Lyrics(file: ByteReader) { + // `moov` may sit after the audio, so walk the top-level box headers. + let offset = 0 + while (offset + 8 <= file.size) { + const head = await file.read(offset, 16) + if (head.length < 8) return null + const data = view(head) + let size = data.getUint32(0) + if (size === 1 && head.length === 16) size = Number(data.getBigUint64(8)) + else if (size === 0) size = file.size - offset + if (size < 8) return null + if (ascii(head, 4, 4) === "moov") { + if (size > MAX_TAG_BYTES) return null + const moov = await file.read(offset, size) + const root = [...boxes(moov, 0, moov.length)][0] + const udta = root && child(moov, root, "udta") + const meta = udta && child(moov, udta, "meta") + // `meta` is a full box: 4 bytes of version and flags precede children. + const ilst = meta && child(moov, meta, "ilst", 4) + const lyr = ilst && child(moov, ilst, "\u00a9lyr") + const text = lyr && child(moov, lyr, "data") + if (!text) return null + // Type (4 bytes) and locale (4 bytes) precede the UTF-8 text. + return utf8.decode( + moov.subarray(text.start + text.header + 8, text.start + text.size) + ) + } + offset += size + } + return null +} + +const VORBIS_LYRICS_KEYS = new Set(["LYRICS", "UNSYNCEDLYRICS"]) + +async function flacLyrics(file: ByteReader) { + let offset = 4 + for (;;) { + const header = await file.read(offset, 4) + if (header.length < 4) return null + const last = (header[0] & 0x80) !== 0 + const type = header[0] & 0x7f + const length = (header[1] << 16) | (header[2] << 8) | header[3] + offset += 4 + if (type === 4) { + const block = await file.read(offset, Math.min(length, MAX_TAG_BYTES)) + const data = view(block) + let at = 4 + data.getUint32(0, true) + const count = data.getUint32(at, true) + at += 4 + for (let i = 0; i < count && at + 4 <= block.length; i++) { + const commentLength = data.getUint32(at, true) + const comment = utf8.decode( + block.subarray(at + 4, at + 4 + commentLength) + ) + at += 4 + commentLength + const equals = comment.indexOf("=") + if (VORBIS_LYRICS_KEYS.has(comment.slice(0, equals).toUpperCase())) { + return comment.slice(equals + 1) + } + } + return null + } + if (last) return null + offset += length + } +} + +function syncsafe(bytes: Uint8Array, at: number) { + return ( + (bytes[at] << 21) | + (bytes[at + 1] << 14) | + (bytes[at + 2] << 7) | + bytes[at + 3] + ) +} + +/** + * Latin-1 (0), UTF-16 with a byte order mark (1) or UTF-16BE (2). Decoded by + * hand because React Native's TextDecoder only knows UTF-8. + */ +function decodeLegacy(raw: Uint8Array, encoding: number) { + let text = "" + if (encoding === 0) { + for (const byte of raw) text += String.fromCharCode(byte) + return text + } + let start = 0 + let bigEndian = encoding === 2 + if (encoding === 1 && raw.length >= 2) { + bigEndian = raw[0] === 0xfe && raw[1] === 0xff + if (bigEndian || (raw[0] === 0xff && raw[1] === 0xfe)) start = 2 + } + for (let i = start; i + 1 < raw.length; i += 2) { + text += String.fromCharCode( + bigEndian ? (raw[i] << 8) | raw[i + 1] : raw[i] | (raw[i + 1] << 8) + ) + } + return text +} + +/** Decodes ID3 text in `encoding`, returning it and where its terminator ends. */ +function id3Text(bytes: Uint8Array, encoding: number, terminated: boolean) { + const wide = encoding === 1 || encoding === 2 + let end = bytes.length + if (terminated) { + for (let i = 0; i < bytes.length; i += wide ? 2 : 1) { + if (bytes[i] === 0 && (!wide || bytes[i + 1] === 0)) { + end = i + break + } + } + } + const raw = bytes.subarray(0, end) + const text = encoding === 3 ? utf8.decode(raw) : decodeLegacy(raw, encoding) + return { text, next: Math.min(bytes.length, end + (wide ? 2 : 1)) } +} + +async function id3Lyrics(file: ByteReader) { + const header = await file.read(0, 10) + const version = header[3] + const size = syncsafe(header, 6) + if (size > MAX_TAG_BYTES) return null + const tag = await file.read(10, size) + const data = view(tag) + let at = 0 + while (at + 10 <= tag.length) { + const id = ascii(tag, at, 4) + if (!/^[A-Z0-9]{4}$/.test(id)) return null + const frameSize = + version === 4 ? syncsafe(tag, at + 4) : data.getUint32(at + 4) + const body = tag.subarray(at + 10, at + 10 + frameSize) + at += 10 + frameSize + if (id !== "USLT" || body.length < 5) continue + const encoding = body[0] + // Encoding, a 3 letter language, then a terminated description. + const description = id3Text(body.subarray(4), encoding, true) + return id3Text(body.subarray(4 + description.next), encoding, false).text + } + return null +} + +/** The raw lyrics tag of an audio file, or null when it has none. */ +export async function readLyricsTag(file: ByteReader): Promise { + const head = await file.read(0, 12) + const magic = ascii(head, 0, 4) + try { + if (magic === "fLaC") return await flacLyrics(file) + if (magic.startsWith("ID3")) return await id3Lyrics(file) + if (ascii(head, 4, 4) === "ftyp") return await mp4Lyrics(file) + } catch { + // An unexpected layout reads as no lyrics; the server copy is used instead. + } + return null +} diff --git a/packages/convex/client/lyrics.ts b/packages/convex/client/lyrics.ts new file mode 100644 index 0000000..804c6d9 --- /dev/null +++ b/packages/convex/client/lyrics.ts @@ -0,0 +1,232 @@ +/** + * Lyrics as tagged in the music files: plain text, LRC (`[mm:ss.xx]line`), or + * word-timed LRC (`word`). The server stores that text unchanged and + * clients parse it here, so a downloaded file's tag and the server copy read + * the same. + */ + +export type LyricWord = { + /** Includes its trailing space, so a line's words join back into its text. */ + text: string + start: number + end: number +} + +export type LyricLine = { + text: string + /** Seconds; `null` for plain lyrics. */ + start: number | null + /** Set only on word-timed lines. */ + words: LyricWord[] | null +} + +export type Lyrics = { + synced: "none" | "line" | "word" + lines: LyricLine[] +} + +const LINE_STAMP = /^\[(\d+):(\d+(?:[.:]\d+)?)\]/ +const WORD_STAMP = /<(\d+):(\d+(?:[.:]\d+)?)>/g +const HAS_WORD_STAMP = /<\d+:\d+(?:[.:]\d+)?>/ +const ID_TAG = /^\[[a-z]+:.*\]$/i + +function seconds(minutes: string, rest: string) { + return Number(minutes) * 60 + Number(rest.replace(":", ".")) +} + +/** Splits `word word` into words; the last stamp ends the last word. */ +function parseWords(body: string): LyricWord[] { + const stamps = [...body.matchAll(WORD_STAMP)] + const words: LyricWord[] = [] + for (let i = 0; i < stamps.length; i++) { + const stamp = stamps[i] + const textStart = stamp.index + stamp[0].length + const next = stamps[i + 1] + const text = body.slice(textStart, next?.index ?? body.length) + const start = seconds(stamp[1], stamp[2]) + if (text.trim()) { + words.push({ + text, + start, + end: next ? seconds(next[1], next[2]) : start, + }) + } + } + return words +} + +export function parseLyrics(raw: string): Lyrics | null { + const rows = raw.replace(/\r\n?/g, "\n").split("\n") + const timed = rows.some((row) => LINE_STAMP.test(row.trim())) + const wordTimed = rows.some((row) => HAS_WORD_STAMP.test(row)) + + if (!timed && !wordTimed) { + const lines = rows.map((row) => ({ + text: row.trim(), + start: null, + words: null, + })) + // Blank rows between stanzas stay as spacing; ones at the ends go. + while (lines[0]?.text === "") lines.shift() + while (lines.at(-1)?.text === "") lines.pop() + return lines.length > 0 ? { synced: "none", lines } : null + } + + const lines: LyricLine[] = [] + for (const row of rows) { + let body = row.trim() + if (ID_TAG.test(body) && !LINE_STAMP.test(body)) continue + // A line may repeat under several stamps: `[00:12.00][01:30.00]Chorus`. + const starts: number[] = [] + for (let match = LINE_STAMP.exec(body); match;) { + starts.push(seconds(match[1], match[2])) + body = body.slice(match[0].length) + match = LINE_STAMP.exec(body) + } + const words = wordTimed ? parseWords(body) : [] + const text = ( + words.length > 0 ? words.map((word) => word.text).join("") : body + ).trim() + if (!text) continue + if (starts.length === 0 && words.length > 0) starts.push(words[0].start) + for (const start of starts) { + const shift = words.length > 0 ? start - words[0].start : 0 + lines.push({ + text, + start, + words: + words.length > 0 + ? words.map((word) => ({ + ...word, + start: word.start + shift, + end: word.end + shift, + })) + : null, + }) + } + } + lines.sort((a, b) => a.start! - b.start!) + if (lines.length === 0) return null + return { + synced: lines.every((line) => line.words) ? "word" : "line", + lines, + } +} + +/** The text without timestamps, one line per row, for search and snippets. */ +export function plainLyrics(lyrics: Lyrics) { + return lyrics.lines.map((line) => line.text).join("\n") +} + +/** How well a tag's lyrics are timed, to keep the best of a song's files. */ +export function lyricsRank(raw: string | null) { + const synced = raw ? parseLyrics(raw)?.synced : undefined + return synced === "word" ? 3 : synced === "line" ? 2 : synced ? 1 : 0 +} + +/** + * The line playing at `time` (the last one started), or -1 before the first. + * Plain lyrics never have one. + */ +export function activeLineIndex(lyrics: Lyrics, time: number) { + let active = -1 + for (let i = 0; i < lyrics.lines.length; i++) { + const start = lyrics.lines[i].start + if (start === null || start > time) break + active = i + } + return active +} + +/** When the highlighted line or word next changes after `time`, if ever. */ +export function nextLyricsChange(lyrics: Lyrics, time: number) { + let next = Infinity + for (const line of lyrics.lines) { + if (line.start !== null && line.start > time) { + next = Math.min(next, line.start) + break + } + for (const word of line.words ?? []) { + if (word.start > time) { + next = Math.min(next, word.start) + break + } + } + } + return next +} + +/** + * While audio plays on from `time` seconds, calls `onChange` with the playback + * time whenever the highlighted line or word changes. Players report progress + * only a few times a second, which is too coarse for word timing. Returns a + * function that stops it. + */ +export function followLyrics( + lyrics: Lyrics, + time: number, + onChange: (time: number) => void +) { + const startedAt = Date.now() - time * 1000 + let timer: ReturnType | undefined + const schedule = (from: number) => { + const next = nextLyricsChange(lyrics, from) + if (!Number.isFinite(next)) return + timer = setTimeout( + () => { + const now = (Date.now() - startedAt) / 1000 + onChange(now) + schedule(now) + }, + (next - from) * 1000 + ) + } + if (lyrics.synced !== "none") schedule(time) + return () => clearTimeout(timer) +} + +/** Lowercase words of a search, for matching lyrics the way the search index does. */ +function searchTerms(query: string): string[] { + return query.toLowerCase().match(/[\p{L}\p{N}']+/gu) ?? [] +} + +const SNIPPET_LEAD = 24 + +export type LyricsMatch = { + /** The matched line, trimmed to start near the match. */ + snippet: string + /** Whether the line holds the query as typed, not just its words. */ + exact: boolean +} + +/** + * Where a search matched the lyrics: a line holding the query as typed, or + * else a line holding every word of it (the last may be a prefix, as when + * typing). Null when no single line does. + */ +export function matchLyrics(plain: string, query: string): LyricsMatch | null { + const needle = query.trim().toLowerCase() + const terms = searchTerms(needle) + const last = terms.at(-1) + if (!needle || last === undefined) return null + + let loose: string | null = null + for (const line of plain.split("\n")) { + const column = line.toLowerCase().indexOf(needle) + if (column !== -1) { + const snippet = + column > SNIPPET_LEAD + ? `…${line.slice(column - SNIPPET_LEAD).trimStart()}` + : line.trim() + return { snippet, exact: true } + } + if (loose === null) { + const words = searchTerms(line) + const hasAll = + terms.slice(0, -1).every((term) => words.includes(term)) && + words.some((word) => word.startsWith(last)) + if (hasAll) loose = line.trim() + } + } + return loose === null ? null : { snippet: loose, exact: false } +} diff --git a/packages/convex/client/song-search.ts b/packages/convex/client/song-search.ts index 954d2e2..248489d 100644 --- a/packages/convex/client/song-search.ts +++ b/packages/convex/client/song-search.ts @@ -1,21 +1,30 @@ type SearchableSong = { + id: string title: string artist: { name: string } album: { title: string } } -/** Case-insensitive match on title, artist, or album. A blank query keeps every song. */ +/** + * Case-insensitive match on title, artist, or album, plus the songs in + * `lyricsMatches` (from `api.lyrics.matchingSongIds`). A blank query keeps + * every song. + */ export function filterSongs( songs: T[], - query: string + query: string, + lyricsMatches?: readonly string[] ) { const normalized = query.trim().toLowerCase() if (!normalized) { return songs } - return songs.filter((song) => - [song.title, song.artist.name, song.album.title].some((value) => - value.toLowerCase().includes(normalized) - ) + const byLyrics = new Set(lyricsMatches) + return songs.filter( + (song) => + byLyrics.has(song.id) || + [song.title, song.artist.name, song.album.title].some((value) => + value.toLowerCase().includes(normalized) + ) ) } diff --git a/packages/convex/convex/_generated/api.d.ts b/packages/convex/convex/_generated/api.d.ts index 3c98aaf..a3e6959 100644 --- a/packages/convex/convex/_generated/api.d.ts +++ b/packages/convex/convex/_generated/api.d.ts @@ -19,6 +19,7 @@ import type * as intentCatalog from "../intentCatalog.js"; import type * as intentCatalogChanges from "../intentCatalogChanges.js"; import type * as library from "../library.js"; import type * as limits from "../limits.js"; +import type * as lyrics from "../lyrics.js"; import type * as migrations from "../migrations.js"; import type * as playback from "../playback.js"; import type * as playbackState from "../playbackState.js"; @@ -46,6 +47,7 @@ declare const fullApi: ApiFromModules<{ intentCatalogChanges: typeof intentCatalogChanges; library: typeof library; limits: typeof limits; + lyrics: typeof lyrics; migrations: typeof migrations; playback: typeof playback; playbackState: typeof playbackState; diff --git a/packages/convex/convex/actions.ts b/packages/convex/convex/actions.ts index eff747c..e10c1b6 100644 --- a/packages/convex/convex/actions.ts +++ b/packages/convex/convex/actions.ts @@ -10,6 +10,7 @@ import { ConvexError } from "convex/values" import type { Id } from "./_generated/dataModel" import { action, internalAction, type ActionCtx } from "./_generated/server" +import { lyricsRank } from "../client/lyrics" const DATA_DIR = process.env.DATA || "/data" const HLS_CACHE_DIR = "/tmp/otunes" @@ -67,6 +68,8 @@ const SCAN_LOCK_LEASE_MS = 15 * 60 * 1000 /** New files left unparsed after this are picked up by the next scan. */ const SCAN_PARSE_BUDGET_MS = 6 * 60 * 1000 const SCAN_BATCH_SIZE = 200 +/** Lyrics text per mutation, well under Convex's argument size limit. */ +const SCAN_BATCH_LYRICS_BYTES = 2 * 1024 * 1024 const FS_CONCURRENCY = 16 type Page = { page: T[]; isDone: boolean; continueCursor: string } @@ -220,6 +223,55 @@ function releaseDate(common: music.ICommonTagsResult) { return common.year ? `01-01-${common.year}` : "" } +const LYRICS_TAG_IDS = new Set(["©LYR", "LYRICS", "UNSYNCEDLYRICS", "USLT"]) + +function lrcStamp(milliseconds: number) { + const totalSeconds = milliseconds / 1000 + const minutes = Math.floor(totalSeconds / 60) + const rest = (totalSeconds - minutes * 60).toFixed(2).padStart(5, "0") + return `[${String(minutes).padStart(2, "0")}:${rest}]` +} + +/** One native tag's lyrics as text; ID3 synced lyrics become LRC. */ +function lyricsTagText({ id, value }: music.ITag): string | null { + const key = id.toUpperCase() + if (typeof value === "string") { + return LYRICS_TAG_IDS.has(key) ? value : null + } + if ( + (key !== "USLT" && key !== "SYLT") || + !value || + typeof value !== "object" + ) { + return null + } + const lyrics = value as music.ILyricsTag + const synced = lyrics.syncText ?? [] + // Timestamp format 2 is milliseconds; frame-based stamps cannot be used. + if (synced.length > 0 && lyrics.timeStampFormat === 2) { + return synced + .map((line) => `${lrcStamp(line.timestamp ?? 0)}${line.text}`) + .join("\n") + } + return lyrics.text ?? null +} + +/** The best timed lyrics tag in a file, or null without one. */ +function lyricsTag(metadata: music.IAudioMetadata): string | null { + let best: string | null = null + for (const tags of Object.values(metadata.native)) { + for (const tag of tags) { + const text = lyricsTagText(tag)?.trim() || null + if (lyricsRank(text) > lyricsRank(best)) best = text + } + } + return best +} + +function betterLyrics(a: string | null, b: string | null) { + return lyricsRank(b) > lyricsRank(a) ? b : a +} + type NewSong = { name: string files: Record @@ -230,6 +282,7 @@ type NewSong = { year: number date: string genres: string[] + lyrics: string | null } type ImportEntry = { @@ -386,9 +439,11 @@ async function scanLibrary(ctx: ActionCtx) { imports.set(key, entry) } + const lyrics = lyricsTag(metadata) const pending = entry.songs.get(title) if (pending) { pending.files[codec] ??= filePath + pending.lyrics = betterLyrics(pending.lyrics, lyrics) continue } entry.songs.set(title, { @@ -402,9 +457,39 @@ async function scanLibrary(ctx: ActionCtx) { year: common.year || 0, date: releaseDate(common), genres: common.genre || [], + lyrics, }) } + // Songs scanned before lyrics were stored, read once for their lyrics. + const unreadLyrics = songs.filter( + (song) => + song.hasLyrics === undefined && + Object.keys(songFiles.get(song._id)!).length > 0 + ) + const readLyrics = await mapLimit( + unreadLyrics, + FS_CONCURRENCY, + async (song) => { + let best: string | null = null + for (const filePath of Object.values(songFiles.get(song._id)!)) { + if (Date.now() > deadline) { + return null + } + try { + const metadata = await music.parseFile(filePath, { + skipCovers: true, + }) + best = betterLyrics(best, lyricsTag(metadata)) + } catch { + // An unreadable file contributes no lyrics. + } + } + return { id: song._id, lyrics: best } + } + ) + const songLyrics = readLyrics.filter((song) => song !== null) + const deletedSongs = songs.flatMap((song) => Object.keys(songFiles.get(song._id)!).length === 0 ? [song._id] : [] ) @@ -469,6 +554,7 @@ async function scanLibrary(ctx: ActionCtx) { let importBatch: ImportEntry[] = [] let importBatchSongs = 0 + let importBatchBytes = 0 const flushImports = async () => { if (importBatch.length === 0) { return @@ -481,16 +567,41 @@ async function scanLibrary(ctx: ActionCtx) { }) importBatch = [] importBatchSongs = 0 + importBatchBytes = 0 } for (const entry of imports.values()) { importBatch.push(entry) importBatchSongs += entry.songs.size - if (importBatchSongs >= SCAN_BATCH_SIZE) { + for (const song of entry.songs.values()) { + importBatchBytes += song.lyrics?.length ?? 0 + } + if ( + importBatchSongs >= SCAN_BATCH_SIZE || + importBatchBytes >= SCAN_BATCH_LYRICS_BYTES + ) { await flushImports() } } await flushImports() + let lyricsBatch: typeof songLyrics = [] + let lyricsBatchBytes = 0 + for (const [index, song] of songLyrics.entries()) { + lyricsBatch.push(song) + lyricsBatchBytes += song.lyrics?.length ?? 0 + if ( + lyricsBatch.length >= SCAN_BATCH_SIZE || + lyricsBatchBytes >= SCAN_BATCH_LYRICS_BYTES || + index === songLyrics.length - 1 + ) { + await ctx.runMutation(internal.lyrics.setSongLyrics, { + songs: lyricsBatch, + }) + lyricsBatch = [] + lyricsBatchBytes = 0 + } + } + for (const batch of chunk(artistCovers, SCAN_BATCH_SIZE)) { await ctx.runMutation(internal.library.updateArtistCovers, { artists: batch, @@ -523,7 +634,8 @@ async function scanLibrary(ctx: ActionCtx) { ) const summary = `songs: ${importedSongs} added, ${updatedSongs.length} updated, ` + - `${deletedSongs.length} removed; albums removed: ${removedAlbums}; ` + + `${deletedSongs.length} removed, ${songLyrics.length} read for lyrics ` + + `(${unreadLyrics.length - songLyrics.length} deferred); albums removed: ${removedAlbums}; ` + `artists removed: ${removedArtists}; covers updated: ` + `${artistCovers.length + albumCovers.length}; ` + `files deferred: ${skipped}; ${Date.now() - startedAt}ms` diff --git a/packages/convex/convex/library.ts b/packages/convex/convex/library.ts index d888382..3c0ae02 100644 --- a/packages/convex/convex/library.ts +++ b/packages/convex/convex/library.ts @@ -18,6 +18,7 @@ import type { LibrarySearchResults, OwnedPlaylistForAdd, PlaylistSummary, + SearchSong, SearchTopResultItem, SidebarPlaylists, } from "./types" @@ -25,6 +26,7 @@ import { purgeFavoriteEntities } from "./favoriteStore" import { chunk, type Chunked } from "./limits" import { recordIntentCatalogChanges } from "./intentCatalogChanges" import { playlistCoverVersion } from "./playlistCover" +import { deleteSongLyrics, searchSongLyrics, writeSongLyrics } from "./lyrics" export type { BrowseAlbum, @@ -39,6 +41,7 @@ export type { LibrarySearchResults, OwnedPlaylistForAdd, PlaylistSummary, + SearchSong, SearchTopResultItem, SidebarPlaylists, } from "./types" @@ -648,6 +651,9 @@ function matchScoreSongArtists( */ const MAX_SEARCH_RESULTS = 500 +/** Songs found by lyrics alone, listed after title, artist and album matches. */ +const MAX_LYRICS_SEARCH_RESULTS = 50 + export const searchLibrary = query({ args: { query: v.string() }, handler: async (ctx, args) => { @@ -732,6 +738,25 @@ export const searchLibrary = query({ (a, b) => b.score - a.score || a.item.title.localeCompare(b.item.title) ) + const songById = new Map(songs.map((song) => [song._id, song])) + const matchedSongIds = new Set(songResults.map((result) => result.item.id)) + const lyricsResults: SearchSong[] = ( + await searchSongLyrics(ctx, args.query, MAX_LYRICS_SEARCH_RESULTS) + ).flatMap(({ song: songId, snippet }) => { + const song = songById.get(songId) + const album = song && albumMap.get(song.album) + const albumArtist = song && artistMap.get(song.albumArtist) + if (!song || !album || !albumArtist || matchedSongIds.has(songId)) { + return [] + } + return [ + { + ...toBrowseSong(song, album, albumArtist), + lyricsSnippet: snippet, + }, + ] + }) + const topResults: SearchTopResultItem[] = [ ...songResults, ...albumResults, @@ -749,9 +774,10 @@ export const searchLibrary = query({ albums: albumResults .slice(0, MAX_SEARCH_RESULTS) .map((result) => result.item), - songs: songResults - .slice(0, MAX_SEARCH_RESULTS) - .map((result) => result.item), + songs: [ + ...songResults.map((result): SearchSong => result.item), + ...lyricsResults, + ].slice(0, MAX_SEARCH_RESULTS), } return result }, @@ -934,11 +960,12 @@ export const scanSongsPage = internalQuery({ const result = await ctx.db.query("songs").paginate(args.paginationOpts) return { ...result, - page: result.page.map(({ _id, name, files, album }) => ({ + page: result.page.map(({ _id, name, files, album, hasLyrics }) => ({ _id, name, files, album, + hasLyrics, })), } }, @@ -1100,6 +1127,8 @@ export const importAlbums = internalMutation({ year: v.number(), date: v.string(), genres: v.array(v.string()), + /** The best lyrics tag among the song's files. */ + lyrics: v.nullable(v.string()), }) ), }) @@ -1130,7 +1159,7 @@ export const importAlbums = internalMutation({ )?._id ?? (await ctx.db.insert("albums", { ...entry.album, artist: artistId })) - for (const song of entry.songs) { + for (const { lyrics, ...song } of entry.songs) { const existing = await ctx.db .query("songs") .withIndex("by_all", (q) => @@ -1146,11 +1175,12 @@ export const importAlbums = internalMutation({ }) continue } - await ctx.db.insert("songs", { + const songId = await ctx.db.insert("songs", { ...song, album: albumId, albumArtist: artistId, }) + await writeSongLyrics(ctx, songId, lyrics) } } }, @@ -1162,6 +1192,7 @@ export const deleteSongs = internalMutation({ handler: async (ctx, args) => { for (const id of args.ids) { await ctx.db.delete("songs", id) + await deleteSongLyrics(ctx, id) } await purgeSongsFromUsersAndPlaylists(ctx, new Set(args.ids)) await recordIntentCatalogChanges(ctx, "song", args.ids, true) diff --git a/packages/convex/convex/lyrics.ts b/packages/convex/convex/lyrics.ts new file mode 100644 index 0000000..7ccbaa2 --- /dev/null +++ b/packages/convex/convex/lyrics.ts @@ -0,0 +1,129 @@ +import { getAuthUserId } from "@convex-dev/auth/server" +import { v } from "convex/values" + +import type { Id } from "./_generated/dataModel" +import { + internalMutation, + query, + type MutationCtx, + type QueryCtx, +} from "./_generated/server" +import { matchLyrics, parseLyrics, plainLyrics } from "../client/lyrics" + +/** Shorter searches match too much of every song to be useful. */ +const MIN_LYRICS_QUERY_LENGTH = 3 + +/** The largest page a search index returns. */ +const MAX_LYRICS_MATCHES = 1_024 + +/** + * Replaces a song's lyrics, or removes them when `text` is null or holds no + * lyrics, and marks the song as read for lyrics. + */ +export async function writeSongLyrics( + ctx: MutationCtx, + songId: Id<"songs">, + text: string | null +) { + const lyrics = text ? parseLyrics(text) : null + const [stored, searchable] = await Promise.all([ + ctx.db + .query("lyrics") + .withIndex("by_song", (q) => q.eq("song", songId)) + .first(), + ctx.db + .query("lyricsSearch") + .withIndex("by_song", (q) => q.eq("song", songId)) + .first(), + ]) + await ctx.db.patch("songs", songId, { hasLyrics: lyrics !== null }) + + if (!lyrics || !text) { + if (stored) await ctx.db.delete("lyrics", stored._id) + if (searchable) await ctx.db.delete("lyricsSearch", searchable._id) + return + } + const plain = plainLyrics(lyrics) + if (stored) await ctx.db.patch("lyrics", stored._id, { text }) + else await ctx.db.insert("lyrics", { song: songId, text }) + if (searchable) await ctx.db.patch("lyricsSearch", searchable._id, { plain }) + else await ctx.db.insert("lyricsSearch", { song: songId, plain }) +} + +/** Removes a deleted song's lyrics. */ +export async function deleteSongLyrics(ctx: MutationCtx, songId: Id<"songs">) { + for (const table of ["lyrics", "lyricsSearch"] as const) { + const row = await ctx.db + .query(table) + .withIndex("by_song", (q) => q.eq("song", songId)) + .first() + if (row) await ctx.db.delete(table, row._id) + } +} + +/** + * Songs with a lyrics line matching `query` (see `matchLyrics`), with that + * line. Lines holding the query as typed come first, then the search index's + * relevance order. The index matches words anywhere in the lyrics, so its + * results are checked line by line. + */ +export async function searchSongLyrics( + ctx: QueryCtx, + query: string, + limit: number +): Promise<{ song: Id<"songs">; snippet: string }[]> { + const text = query.trim() + if (text.length < MIN_LYRICS_QUERY_LENGTH) return [] + const rows = await ctx.db + .query("lyricsSearch") + .withSearchIndex("search_plain", (q) => q.search("plain", text)) + .take(limit) + const matches = rows.flatMap((row) => { + const match = matchLyrics(row.plain, text) + return match ? [{ song: row.song, ...match }] : [] + }) + return [ + ...matches.filter((match) => match.exact), + ...matches.filter((match) => !match.exact), + ].map(({ song, snippet }) => ({ song, snippet })) +} + +/** The song's lyrics tag (see `client/lyrics.ts`), or null without lyrics. */ +export const forSong = query({ + args: { id: v.id("songs") }, + handler: async (ctx, args): Promise => { + if ((await getAuthUserId(ctx)) === null) return null + const row = await ctx.db + .query("lyrics") + .withIndex("by_song", (q) => q.eq("song", args.id)) + .first() + return row?.text ?? null + }, +}) + +/** Songs whose lyrics match a search, so in-list filters can include them. */ +export const matchingSongIds = query({ + args: { query: v.string() }, + handler: async (ctx, args): Promise[]> => { + if ((await getAuthUserId(ctx)) === null) return [] + const matches = await searchSongLyrics(ctx, args.query, MAX_LYRICS_MATCHES) + return matches.map((match) => match.song) + }, +}) + +/** Stores lyrics the library scan read from files; null marks none found. */ +export const setSongLyrics = internalMutation({ + args: { + songs: v.array( + v.object({ id: v.id("songs"), lyrics: v.nullable(v.string()) }) + ), + }, + handler: async (ctx, args) => { + for (const song of args.songs) { + // The song may have been deleted since the scan read it. + if (await ctx.db.get("songs", song.id)) { + await writeSongLyrics(ctx, song.id, song.lyrics) + } + } + }, +}) diff --git a/packages/convex/convex/schema.ts b/packages/convex/convex/schema.ts index e7596fc..1487a54 100644 --- a/packages/convex/convex/schema.ts +++ b/packages/convex/convex/schema.ts @@ -140,11 +140,28 @@ export default defineSchema({ year: v.number(), date: v.string(), genres: v.array(v.string()), + /** + * Whether the files have a lyrics tag, stored in `lyrics`. Unset until the + * library scan has read the files for lyrics. + */ + hasLyrics: v.optional(v.boolean()), }) .index("by_name", ["name"]) .index("by_artist", ["albumArtist"]) .index("by_album", ["album"]) .index("by_all", ["name", "albumArtist", "album"]), + /** A song's lyrics tag as written in its file: plain, LRC, or word-timed LRC. */ + lyrics: defineTable({ + song: v.id("songs"), + text: v.string(), + }).index("by_song", ["song"]), + /** The same lyrics without timestamps. Kept apart so search reads only this. */ + lyricsSearch: defineTable({ + song: v.id("songs"), + plain: v.string(), + }) + .index("by_song", ["song"]) + .searchIndex("search_plain", { searchField: "plain" }), playlists: defineTable({ name: v.string(), owner: v.id("users"), diff --git a/packages/convex/convex/types.ts b/packages/convex/convex/types.ts index 160e8f5..718460b 100644 --- a/packages/convex/convex/types.ts +++ b/packages/convex/convex/types.ts @@ -95,11 +95,15 @@ export type SearchTopResultItem = | { kind: "album"; item: BrowseAlbum } | { kind: "artist"; item: BrowseArtist } +/** A song search result. Songs found only by their lyrics carry the matched line. */ +export type SearchSong = BrowseSong & { lyricsSnippet?: string } + export type LibrarySearchResults = { topResults: SearchTopResultItem[] artists: BrowseArtist[] albums: BrowseAlbum[] - songs: BrowseSong[] + /** Title, artist and album matches, then lyrics matches. */ + songs: SearchSong[] } export type QueueSong = BrowseSong & { queueIndex: number } diff --git a/packages/convex/package.json b/packages/convex/package.json index b1e5cd3..c3735e0 100644 --- a/packages/convex/package.json +++ b/packages/convex/package.json @@ -51,6 +51,14 @@ "types": "./client/favorites.ts", "default": "./client/favorites.ts" }, + "./client/lyrics": { + "types": "./client/lyrics.ts", + "default": "./client/lyrics.ts" + }, + "./client/lyrics-tags": { + "types": "./client/lyrics-tags.ts", + "default": "./client/lyrics-tags.ts" + }, "./client/media-links": { "types": "./client/media-links.ts", "default": "./client/media-links.ts"