Files
otunes/apps/mobile/components/lyrics-view.tsx
T
joshuafhigginsandClaude Opus 5.5 Verified 55de91084c 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 <noreply@anthropic.com>
2026-11-20 15:52:22 -05:00

352 lines
9.5 KiB
TypeScript

import {
memo,
type ComponentType,
type ReactElement,
useCallback,
useEffect,
useMemo,
useRef,
useState,
} from "react"
import {
Pressable,
ScrollView,
StyleSheet,
Text,
View,
type ScrollViewInstance,
type ViewProps,
} from "react-native"
import MaskedViewClass from "@react-native-masked-view/masked-view"
import Animated, {
useAnimatedStyle,
type SharedValue,
} from "react-native-reanimated"
import {
usePlaybackActions,
usePlaybackProgress,
usePlaybackQueue,
} from "@/contexts/playback"
import { useLyricsTime, usePlaybackClock } from "@/hooks/use-lyrics"
import type { NowPlayingColors } from "@/lib/now-playing-colors"
import {
activeLineIndex,
type LyricLine,
type LyricWord,
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
* 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 (
<View style={styles.empty}>
<Text style={[styles.emptyText, { color: colors.secondaryForeground }]}>
No lyrics
</Text>
</View>
)
}
return <LyricsLines lyrics={lyrics} colors={colors} fontSize={fontSize} />
}
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 clock = usePlaybackClock(currentTime, isPlaying)
const active = activeLineIndex(lyrics, time)
const synced = lyrics.synced !== "none"
const scrollRef = useRef<ScrollViewInstance>(null)
const lineOffsets = useRef<number[]>([])
const [height, setHeight] = useState(0)
// While the listener scrolls, lines stay sharp and the view stays put.
const [browsing, setBrowsing] = useState(false)
const browseTimer = useRef<ReturnType<typeof setTimeout>>(undefined)
useEffect(() => () => clearTimeout(browseTimer.current), [])
const scrollToLine = useCallback(
(index: number) => {
const y = lineOffsets.current[Math.max(index, 0)]
if (y === undefined || !synced || height === 0 || browsing) return
scrollRef.current?.scrollTo({
y: Math.max(0, y - height * ACTIVE_LINE_POSITION),
animated: true,
})
},
[height, synced, browsing]
)
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)
clearTimeout(browseTimer.current)
setBrowsing(false)
},
[seekTo, setIsPlaying]
)
const releaseScroll = () => {
clearTimeout(browseTimer.current)
browseTimer.current = setTimeout(
() => setBrowsing(false),
MANUAL_SCROLL_HOLD_MS
)
}
const lineStyle = useMemo(
() => ({ fontSize, lineHeight: Math.round(fontSize * 1.18) }),
[fontSize]
)
return (
<ScrollView
ref={scrollRef}
style={styles.fill}
contentContainerStyle={{
paddingTop: height * ACTIVE_LINE_POSITION,
paddingBottom: height * 0.7,
}}
showsVerticalScrollIndicator={false}
onLayout={(event) => setHeight(event.nativeEvent.layout.height)}
onScrollBeginDrag={() => {
clearTimeout(browseTimer.current)
setBrowsing(true)
}}
// Hold from when the scroll settles, not when the finger lifted.
onScrollEndDrag={releaseScroll}
onMomentumScrollEnd={releaseScroll}
>
{lyrics.lines.map((line, index) =>
synced ? (
<SyncedLine
key={index}
index={index}
line={line}
distance={
browsing
? 0
: Math.min(Math.abs(index - active), LINE_BLUR.length - 1)
}
active={index === active}
clock={clock}
colors={colors}
textStyle={lineStyle}
onSelect={playFrom}
onLayoutY={handleLineLayout}
/>
) : (
<Text
key={index}
style={[
styles.plainLine,
{
color: colors.foreground,
fontSize: fontSize * 0.75,
lineHeight: Math.round(fontSize * 0.75 * 1.25),
},
line.text === "" && styles.stanzaGap,
]}
>
{line.text}
</Text>
)
)}
</ScrollView>
)
}
/**
* 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,
clock,
colors,
textStyle,
onSelect,
onLayoutY,
}: {
index: number
line: LyricLine
distance: number
active: boolean
clock: SharedValue<number>
colors: NowPlayingColors
textStyle: { fontSize: number; lineHeight: number }
onSelect: (seconds: number) => void
onLayoutY: (index: number, y: number) => void
}) {
const wordStyle = [styles.lineText, textStyle, { color: colors.foreground }]
return (
<Pressable
onPress={() => onSelect(line.start ?? 0)}
onLayout={(event) => onLayoutY(index, event.nativeEvent.layout.y)}
accessibilityRole="button"
accessibilityHint="Plays from this line"
style={styles.line}
>
<Animated.View
style={{
opacity: active ? 1 : INACTIVE_LINE_OPACITY,
filter: [{ blur: LINE_BLUR[distance] }],
transitionProperty: ["opacity", "filter"],
transitionDuration: LINE_FADE_MS,
}}
>
{line.words ? (
<View
style={[styles.words, { columnGap: textStyle.fontSize * 0.25 }]}
>
{line.words.map((word, wordIndex) =>
active ? (
<FilledWord
key={wordIndex}
word={word}
clock={clock}
colors={colors}
textStyle={textStyle}
/>
) : (
<Text key={wordIndex} style={wordStyle}>
{word.text.trim()}
</Text>
)
)}
</View>
) : (
<Text style={wordStyle}>{line.text}</Text>
)}
</Animated.View>
</Pressable>
)
})
/**
* 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 FilledWord({
word,
clock,
colors,
textStyle,
}: {
word: LyricWord
clock: SharedValue<number>
colors: NowPlayingColors
textStyle: { fontSize: number; lineHeight: number }
}) {
const text = word.text.trim()
const slide = useAnimatedStyle(() => {
const progress =
(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 (
<MaskedView
maskElement={
<Text style={[styles.lineText, textStyle, styles.mask]}>{text}</Text>
}
>
{/* Sizes the word; the mask draws it. */}
<Text style={[styles.lineText, textStyle, styles.hidden]}>{text}</Text>
<Animated.View
style={[
styles.fillGradient,
{
backgroundImage: `linear-gradient(90deg, ${colors.foreground} 40%, ${colors.lyricsUnsung} 60%)`,
},
slide,
]}
/>
</MaskedView>
)
}
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" },
words: { flexDirection: "row", flexWrap: "wrap" },
mask: { color: "black" },
hidden: { opacity: 0 },
fillGradient: {
position: "absolute",
top: 0,
bottom: 0,
left: 0,
width: "250%",
},
plainLine: { fontWeight: "700", paddingVertical: 2 },
stanzaGap: { height: 18 },
})