From 55de91084cb80bd6d9d4c022f6da14ac253dd114 Mon Sep 17 00:00:00 2001 From: Joshua Higgins Date: Fri, 20 Nov 2026 15:52:22 -0500 Subject: [PATCH] fix(mobile): fill lyrics as smoothly as web The mobile fill restarted on every progress update and word boundary, so it hitched; it had a hard edge, re-wrapped the playing line, and line changes snapped. A UI-thread clock now drives fills and resets only on drift, words fill through a gradient mask like web, lines always lay out word by word, and opacity and blur fade between lines. Co-Authored-By: Claude Opus 5.5 --- apps/mobile/components/lyrics-view.tsx | 212 +++++++++++-------------- apps/mobile/hooks/use-lyrics.ts | 51 +++++- apps/mobile/lib/now-playing-colors.ts | 3 - apps/mobile/package.json | 1 + pnpm-lock.yaml | 3 + 5 files changed, 148 insertions(+), 122 deletions(-) diff --git a/apps/mobile/components/lyrics-view.tsx b/apps/mobile/components/lyrics-view.tsx index f73dce5..f1e7bff 100644 --- a/apps/mobile/components/lyrics-view.tsx +++ b/apps/mobile/components/lyrics-view.tsx @@ -1,4 +1,13 @@ -import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react" +import { + memo, + type ComponentType, + type ReactElement, + useCallback, + useEffect, + useMemo, + useRef, + useState, +} from "react" import { Pressable, ScrollView, @@ -6,14 +15,11 @@ import { Text, View, type ScrollViewInstance, + type ViewProps, } from "react-native" +import MaskedViewClass from "@react-native-masked-view/masked-view" import Animated, { - cancelAnimation, - Easing, useAnimatedStyle, - useSharedValue, - withSequence, - withTiming, type SharedValue, } from "react-native-reanimated" @@ -22,7 +28,7 @@ import { usePlaybackProgress, usePlaybackQueue, } from "@/contexts/playback" -import { useLyricsTime } from "@/hooks/use-lyrics" +import { useLyricsTime, usePlaybackClock } from "@/hooks/use-lyrics" import type { NowPlayingColors } from "@/lib/now-playing-colors" import { activeLineIndex, @@ -31,12 +37,21 @@ import { type Lyrics, } from "@otunes/convex/client/lyrics" +// The package's class typings predate React 19's; this is its documented API. +const MaskedView = MaskedViewClass as unknown as ComponentType< + ViewProps & { maskElement: ReactElement } +> + /** 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 /** Blur radius by distance from the playing line; farther lines share the last. */ const LINE_BLUR = [0, 1, 2, 3] +/** Opacity of lines other than the one playing. */ +const INACTIVE_LINE_OPACITY = 0.35 +/** How long a line takes to brighten, dim, or change blur. */ +const LINE_FADE_MS = 300 /** * Lyrics in the player's own colors. Synced lines follow playback and seek @@ -77,6 +92,7 @@ function LyricsLines({ const { isPlaying } = usePlaybackQueue() const { seekTo, setIsPlaying } = usePlaybackActions() const time = useLyricsTime(lyrics, currentTime, isPlaying) + const clock = usePlaybackClock(currentTime, isPlaying) const active = activeLineIndex(lyrics, time) const synced = lyrics.synced !== "none" const scrollRef = useRef(null) @@ -170,8 +186,7 @@ function LyricsLines({ : Math.min(Math.abs(index - active), LINE_BLUR.length - 1) } active={index === active} - time={index === active ? time : null} - isPlaying={isPlaying} + clock={clock} colors={colors} textStyle={lineStyle} onSelect={playFrom} @@ -199,17 +214,16 @@ function LyricsLines({ } /** - * One timed line, blurred by its `distance` from the playing line. Only the - * playing line gets the time, so the others skip re-rendering as the song - * plays. + * One timed line, laid out word by word whether or not it is playing, so it + * never re-wraps. It fades and blurs by its `distance` from the playing line, + * and only the playing line's words fill. */ const SyncedLine = memo(function SyncedLine({ index, line, distance, active, - time, - isPlaying, + clock, colors, textStyle, onSelect, @@ -219,140 +233,100 @@ const SyncedLine = memo(function SyncedLine({ line: LyricLine distance: number active: boolean - time: number | null - isPlaying: boolean + clock: SharedValue colors: NowPlayingColors textStyle: { fontSize: number; lineHeight: number } onSelect: (seconds: number) => void onLayoutY: (index: number, y: number) => void }) { - const blur = LINE_BLUR[distance] + const wordStyle = [styles.lineText, textStyle, { color: colors.foreground }] return ( onSelect(line.start ?? 0)} onLayout={(event) => onLayoutY(index, event.nativeEvent.layout.y)} accessibilityRole="button" accessibilityHint="Plays from this line" - style={[styles.line, blur > 0 && { filter: [{ blur }] }]} + style={styles.line} > - {active && line.words && time !== null ? ( - - ) : ( - - {line.text} - - )} + + {line.words ? ( + + {line.words.map((word, wordIndex) => + active ? ( + + ) : ( + + {word.text.trim()} + + ) + )} + + ) : ( + {line.text} + )} + ) }) /** - * The playing line's words, each wiping from dim to bright as it is sung. - * Reanimated runs the wipe; playback updates only re-anchor it. + * A word of the playing line, filled from dim to bright with a soft edge as + * it is sung: a gradient 2.5 times its width slides under the word's + * shape, like the web panel's. */ -function FilledWords({ - words, - time, - isPlaying, - colors, - textStyle, -}: { - words: LyricWord[] - time: number - isPlaying: boolean - colors: NowPlayingColors - textStyle: { fontSize: number; lineHeight: number } -}) { - const sung = useSharedValue(time) - const end = words.at(-1)?.end ?? time - - useEffect(() => { - cancelAnimation(sung) - // Jump to the reported time first, so the wipe never runs from a stale one. - sung.value = - isPlaying && end > time - ? withSequence( - withTiming(time, { duration: 0 }), - withTiming(end, { - duration: (end - time) * 1000, - easing: Easing.linear, - }) - ) - : time - }, [sung, time, isPlaying, end]) - - return ( - - {words.map((word, index) => ( - - ))} - - ) -} - function FilledWord({ word, - sung, + clock, colors, textStyle, }: { word: LyricWord - sung: SharedValue + clock: SharedValue colors: NowPlayingColors textStyle: { fontSize: number; lineHeight: number } }) { - const [width, setWidth] = useState(0) const text = word.text.trim() - const wipe = useAnimatedStyle(() => { + const slide = useAnimatedStyle(() => { const progress = - (sung.value - word.start) / Math.max(word.end - word.start, 0.05) - return { width: width * Math.min(Math.max(progress, 0), 1) } + (clock.value - word.start) / Math.max(word.end - word.start, 0.05) + const sung = Math.min(Math.max(progress, 0), 1) + // -60% of the gradient's width shows its dim end; 0% its bright one. + return { transform: [{ translateX: `${-60 * (1 - sung)}%` }] } }) return ( - - setWidth(event.nativeEvent.layout.width)} - > - {text} - - - - {text} - - - + {text} + } + > + {/* Sizes the word; the mask draws it. */} + {text} + + ) } @@ -363,12 +337,14 @@ const styles = StyleSheet.create({ line: { paddingVertical: 9 }, lineText: { fontWeight: "800" }, words: { flexDirection: "row", flexWrap: "wrap" }, - wipe: { + mask: { color: "black" }, + hidden: { opacity: 0 }, + fillGradient: { position: "absolute", top: 0, bottom: 0, left: 0, - overflow: "hidden", + width: "250%", }, plainLine: { fontWeight: "700", paddingVertical: 2 }, stanzaGap: { height: 18 }, diff --git a/apps/mobile/hooks/use-lyrics.ts b/apps/mobile/hooks/use-lyrics.ts index bd27a41..afa68a5 100644 --- a/apps/mobile/hooks/use-lyrics.ts +++ b/apps/mobile/hooks/use-lyrics.ts @@ -1,5 +1,18 @@ import { File } from "expo-file-system" -import { useEffect, useMemo, useState, useSyncExternalStore } from "react" +import { + useEffect, + useMemo, + useRef, + useState, + useSyncExternalStore, +} from "react" +import { + cancelAnimation, + Easing, + useSharedValue, + withSequence, + withTiming, +} from "react-native-reanimated" import { api } from "@otunes/convex/_generated/api" import type { Id } from "@otunes/convex/_generated/dataModel" @@ -107,3 +120,39 @@ export function useLyricsTime( ? advanced.time : currentTime } + +/** How far the clock may drift from the player before it is reset. */ +const CLOCK_DRIFT_SECONDS = 0.15 +/** How far ahead the clock runs on its own; progress updates come long before. */ +const CLOCK_RUN_SECONDS = 3600 + +/** + * Playback time in seconds on the UI thread, running smoothly between the + * player's progress updates. It is reset only when it drifts, so animations + * driven by it never restart mid-word. + */ +export function usePlaybackClock(currentTime: number, isPlaying: boolean) { + const clock = useSharedValue(currentTime) + const running = useRef(false) + + useEffect(() => { + if (!isPlaying) { + running.current = false + cancelAnimation(clock) + clock.value = currentTime + return + } + const drift = Math.abs(clock.value - currentTime) + if (running.current && drift < CLOCK_DRIFT_SECONDS) return + running.current = true + clock.value = withSequence( + withTiming(currentTime, { duration: 0 }), + withTiming(currentTime + CLOCK_RUN_SECONDS, { + duration: CLOCK_RUN_SECONDS * 1000, + easing: Easing.linear, + }) + ) + }, [clock, currentTime, isPlaying]) + + return clock +} diff --git a/apps/mobile/lib/now-playing-colors.ts b/apps/mobile/lib/now-playing-colors.ts index c898293..ff3c76c 100644 --- a/apps/mobile/lib/now-playing-colors.ts +++ b/apps/mobile/lib/now-playing-colors.ts @@ -12,8 +12,6 @@ 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 @@ -32,7 +30,6 @@ 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/mobile/package.json b/apps/mobile/package.json index 76183a2..6d9b1d2 100644 --- a/apps/mobile/package.json +++ b/apps/mobile/package.json @@ -20,6 +20,7 @@ "@otunes/convex": "workspace:*", "@react-native-async-storage/async-storage": "2.2.0", "@react-native-community/slider": "5.2.1", + "@react-native-masked-view/masked-view": "0.3.2", "@react-native/metro-config": "0.88.0", "convex": "^1.40.0", "expo": "~58.0.17", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9ee885a..ed2ceb5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -279,6 +279,9 @@ importers: '@react-native-community/slider': specifier: 5.2.1 version: 5.2.1(patch_hash=73deacaea9aae000a42050d343517da9e16e736e92a4fff3f61f81dba093a1c4) + '@react-native-masked-view/masked-view': + specifier: 0.3.2 + version: 0.3.2(react-native@0.88.0(@babel/core@7.29.7(supports-color@8.1.1))(@react-native/metro-config@0.88.0(@babel/core@7.29.7(supports-color@8.1.1))(supports-color@8.1.1))(@types/react@19.3.0)(react@19.3.0)(supports-color@8.1.1))(react@19.3.0) '@react-native/metro-config': specifier: 0.88.0 version: 0.88.0(@babel/core@7.29.7(supports-color@8.1.1))(supports-color@8.1.1)