feat: add romaji lyrics display (#2180)

mpv/ffmpeg had no network-level timeout or reconnect options, so a
network stream left open across a system sleep would block forever on
the now-dead TCP connection instead of failing or reconnecting. Since
Node-MPV's IPC commands only resolve when mpv replies, a wedged mpv
process also made quit()/restart hang indefinitely, so the only way
out was to kill the whole app.

- Add --network-timeout and ffmpeg reconnect options to mpv's default
  parameters so a stalled stream fails fast instead of hanging.
- Make the quit() helper resilient to an unresponsive mpv process by
  racing it against a timeout and force-killing as a fallback.
- Listen for Electron's powerMonitor 'resume' event and tell the
  renderer to reload mpv, so playback recovers automatically instead
  of requiring a manual app restart.

src/i18n/locales/en.json

@@ -845,6 +845,8 @@
         "enableAutoTranslation": "Enable auto translation",
         "enableFurigana_description": "Display pronunciation guides (furigana) over Japanese kanji lyrics.",
         "enableFurigana": "Enable furigana generation",
+        "enableRomaji_description": "Display a romaji pronunciation line under Japanese lyrics.",
+        "enableRomaji": "Enable romaji generation",
         "equalizer_descriptionMpv": "Parametric equalizer via FFmpeg lavfi (MPV)",
         "equalizer_descriptionWebAudio": "Parametric equalizer via Web Audio API",
         "equalizer": "Equalizer",

src/main/features/core/lyrics/furigana.ts

@@ -7,16 +7,19 @@ let kuroshiroInstance: any = null;
 let initPromise: null | Promise<void> = null;
 
 const getKuroshiro = async () => {
-    if (kuroshiroInstance) return kuroshiroInstance;
     if (initPromise) {
         await initPromise;
         return kuroshiroInstance;
     }
 
+    if (kuroshiroInstance) return kuroshiroInstance;
+
     const KuroshiroClass = (Kuroshiro as any).default || Kuroshiro;
     kuroshiroInstance = new KuroshiroClass();
     initPromise = kuroshiroInstance.init(new KuromojiAnalyzer());
     await initPromise;
+
+    initPromise = null;
     return kuroshiroInstance;
 };
 
@@ -35,3 +38,17 @@ export const convertFurigana = async (text: string): Promise<string> => {
         return text;
     }
 };
+
+export const convertRomaji = async (text: string): Promise<string> => {
+    const KuroshiroClass = (Kuroshiro as any).default || Kuroshiro;
+
+    if (!KuroshiroClass.Util.hasKana(text)) return text;
+
+    try {
+        const kuroshiro = await getKuroshiro();
+        return await kuroshiro.convert(text, { mode: 'spaced', to: 'romaji' });
+    } catch (e) {
+        console.error('Romaji conversion error: ', e);
+        return text;
+    }
+};

src/main/features/core/lyrics/index.ts

@@ -1,7 +1,7 @@
 import { ipcMain } from 'electron';
 
 import { store } from '../settings';
-import { convertFurigana } from './furigana';
+import { convertFurigana, convertRomaji } from './furigana';
 import { getLyricsBySongId as getGenius, getSearchResults as searchGenius } from './genius';
 import { getLyricsBySongId as getLrcLib, getSearchResults as searchLrcLib } from './lrclib';
 import { getLyricsBySongId as getNetease, getSearchResults as searchNetease } from './netease';
@@ -236,3 +236,7 @@ ipcMain.handle('lyric-by-remote-id', async (_event, params: LyricGetQuery) => {
 ipcMain.handle('lyric-convert-furigana', async (_event, text: string) => {
     return await convertFurigana(text);
 });
+
+ipcMain.handle('lyric-convert-romaji', async (_event, text: string) => {
+    return await convertRomaji(text);
+});

src/main/features/core/player/index.ts

@@ -1,5 +1,5 @@
 import console from 'console';
-import { app, ipcMain } from 'electron';
+import { app, ipcMain, powerMonitor } from 'electron';
 import { access, rm } from 'fs/promises';
 import uniq from 'lodash/uniq';
 import MpvAPI from 'node-mpv';
@@ -85,6 +85,19 @@ const DEFAULT_MPV_PARAMETERS = (extraParameters?: string[]) => {
         parameters.push('--prefetch-playlist=yes');
     }
 
+    // Without these, mpv/ffmpeg will block indefinitely on a dead TCP connection
+    // instead of failing or reconnecting. This commonly happens when the OS network
+    // adapter resets after the system wakes from sleep while a stream is open.
+    if (!extraParameters?.some((param) => param.startsWith('--network-timeout'))) {
+        parameters.push('--network-timeout=10');
+    }
+
+    if (!extraParameters?.some((param) => param.startsWith('--stream-lavf-o'))) {
+        parameters.push(
+            '--stream-lavf-o=reconnect=1,reconnect_streamed=1,reconnect_at_eof=1,reconnect_delay_max=5',
+        );
+    }
+
     return parameters;
 };
 
@@ -191,21 +204,44 @@ export const getMpvInstance = () => {
     return mpvInstance;
 };
 
+const QUIT_TIMEOUT_MS = 3000;
+
+const killMpvProcess = (mpv: MpvAPI) => {
+    const mpvProcess = (mpv as any).process || (mpv as any).mpvProcess;
+    if (mpvProcess && typeof mpvProcess.kill === 'function') {
+        try {
+            mpvProcess.kill('SIGTERM');
+        } catch (killErr) {
+            mpvLog({ action: 'Failed to kill mpv process' }, killErr as NodeMpvError);
+        }
+    }
+};
+
 const quit = async (instance?: MpvAPI | null) => {
     const mpv = instance || getMpvInstance();
     if (mpv) {
         try {
-            await mpv.quit();
+            // mpv.quit() resolves only when mpv replies over IPC. If mpv's command queue
+            // is wedged (e.g. blocked on a dead network stream after the system resumes
+            // from sleep), that reply never arrives, so this must not be allowed to hang
+            // forever - fall back to killing the process directly.
+            let timedOut = false;
+            await Promise.race([
+                mpv.quit(),
+                new Promise((resolve) => {
+                    setTimeout(() => {
+                        timedOut = true;
+                        resolve(undefined);
+                    }, QUIT_TIMEOUT_MS);
+                }),
+            ]);
+
+            if (timedOut) {
+                killMpvProcess(mpv);
+            }
         } catch {
             // If quit() fails, try to kill the process directly
-            const mpvProcess = (mpv as any).process || (mpv as any).mpvProcess;
-            if (mpvProcess && typeof mpvProcess.kill === 'function') {
-                try {
-                    mpvProcess.kill('SIGTERM');
-                } catch (killErr) {
-                    mpvLog({ action: 'Failed to kill mpv process' }, killErr as NodeMpvError);
-                }
-            }
+            killMpvProcess(mpv);
         }
         if (!isWindows()) {
             try {
@@ -666,6 +702,17 @@ const cleanupMpv = async (force = false) => {
     }
 };
 
+// When the OS resumes from sleep, any network stream mpv had open is likely dead
+// (the connection silently dropped while the network adapter was suspended). Tell
+// the renderer to reload mpv so it reconnects with a fresh stream instead of staying
+// stuck on the old, now-dead connection until the app is manually restarted.
+powerMonitor.on('resume', () => {
+    if (getMpvInstance()) {
+        mpvLog({ action: 'System resumed from sleep, reloading mpv' });
+        getMainWindow()?.webContents.send('renderer-mpv-reconnect');
+    }
+});
+
 app.on('before-quit', async (event) => {
     switch (mpvState) {
         case MpvState.DONE:

src/preload/lyrics.ts

@@ -30,8 +30,13 @@ const convertFurigana = (text: string): Promise<string> => {
     return ipcRenderer.invoke('lyric-convert-furigana', text);
 };
 
+const convertRomaji = (text: string): Promise<string> => {
+    return ipcRenderer.invoke('lyric-convert-romaji', text);
+};
+
 export const lyrics = {
     convertFurigana,
+    convertRomaji,
     getRemoteLyricsByRemoteId,
     getRemoteLyricsBySong,
     searchRemoteLyrics,

src/preload/mpv-player.ts

@@ -174,6 +174,10 @@ const rendererPlayerFallback = (cb: (data: boolean) => void) => {
     ipcRenderer.on('renderer-player-fallback', (_, data) => cb(data));
 };
 
+const rendererMpvReconnect = (cb: () => void) => {
+    ipcRenderer.on('renderer-mpv-reconnect', () => cb());
+};
+
 export const mpvPlayer = {
     autoNext,
     cleanup,
@@ -205,6 +209,7 @@ export const mpvPlayerListener = {
     rendererAutoNext,
     rendererCurrentTime,
     rendererError,
+    rendererMpvReconnect,
     rendererNext,
     rendererPause,
     rendererPlay,

src/renderer/features/lyrics/components/lyrics-settings-form.tsx

@@ -307,6 +307,20 @@ export const LyricsSettingsForm = ({ settingsKey }: LyricsSettingsFormProps) =>
             isHidden: !isElectron(),
             title: t('setting.enableFurigana'),
         },
+        {
+            control: (
+                <Switch
+                    aria-label="Enable romaji"
+                    defaultChecked={lyricsSettings.enableRomaji}
+                    onChange={(e) => updateLyricsSetting({ enableRomaji: e.currentTarget.checked })}
+                />
+            ),
+            description: t('setting.enableRomaji', {
+                context: 'description',
+            }),
+            isHidden: !isElectron(),
+            title: t('setting.enableRomaji'),
+        },
         {
             control: (
                 <Switch

src/renderer/features/lyrics/hooks/use-furigana-lyrics.ts

@@ -28,3 +28,27 @@ export const useFuriganaLyrics = (lyrics: LyricsResponse | null | undefined, ena
         staleTime: Infinity,
     });
 };
+
+export const useRomajiLyrics = (lyrics: LyricsResponse | null | undefined, enabled: boolean) => {
+    return useQuery({
+        enabled: enabled && !!lyrics && !!lyricsApi,
+        queryFn: async () => {
+            if (!lyrics || !lyricsApi || !enabled) return lyrics;
+
+            if (typeof lyrics === 'string') {
+                return await lyricsApi.convertRomaji(lyrics);
+            } else if (Array.isArray(lyrics)) {
+                const text = lyrics.map(([, line]) => line).join('\n');
+                const converted = await lyricsApi.convertRomaji(text);
+                const convertedLines = converted.split('\n');
+                return lyrics.map(([time], i) => [
+                    time,
+                    convertedLines[i] ?? lyrics[i][1],
+                ]) as SynchronizedLyricsArray;
+            }
+            return lyrics;
+        },
+        queryKey: ['romaji', lyrics],
+        staleTime: Infinity,
+    });
+};

src/renderer/features/lyrics/lyric-line.module.css

@@ -25,3 +25,8 @@
 .lyric-line:global(.synchronized) {
     cursor: pointer;
 }
+
+.romaji-line {
+    font-size: 0.8em;
+    font-weight: 600;
+}

src/renderer/features/lyrics/lyric-line.tsx

@@ -10,11 +10,21 @@ import { Stack } from '/@/shared/components/stack/stack';
 interface LyricLineProps extends ComponentPropsWithoutRef<'div'> {
     alignment: 'center' | 'left' | 'right';
     fontSize: number;
+    romajiText?: null | string;
     text: string;
+    translatedText?: null | string;
 }
 
 export const LyricLine = memo(
-    ({ alignment, className, fontSize, text, ...props }: LyricLineProps) => {
+    ({
+        alignment,
+        className,
+        fontSize,
+        romajiText,
+        text,
+        translatedText,
+        ...props
+    }: LyricLineProps) => {
         const lines = useMemo(() => text.split('_BREAK_'), [text]);
 
         const style = useMemo(
@@ -31,6 +41,15 @@ export const LyricLine = memo(
                     {lines.map((line, index) => (
                         <span dangerouslySetInnerHTML={{ __html: sanitize(line) }} key={index} />
                     ))}
+                    {romajiText && (
+                        <span
+                            className={styles.romajiLine}
+                            dangerouslySetInnerHTML={{ __html: sanitize(romajiText) }}
+                        />
+                    )}
+                    {translatedText && (
+                        <span dangerouslySetInnerHTML={{ __html: sanitize(translatedText) }} />
+                    )}
                 </Stack>
             </Box>
         );

src/renderer/features/lyrics/lyrics.tsx

@@ -14,7 +14,10 @@ import {
     type LyricsQueryResult,
 } from '/@/renderer/features/lyrics/api/lyrics-api';
 import { openLyricsExportModal } from '/@/renderer/features/lyrics/components/lyrics-export-form';
-import { useFuriganaLyrics } from '/@/renderer/features/lyrics/hooks/use-furigana-lyrics';
+import {
+    useFuriganaLyrics,
+    useRomajiLyrics,
+} from '/@/renderer/features/lyrics/hooks/use-furigana-lyrics';
 import { LyricsActions } from '/@/renderer/features/lyrics/lyrics-actions';
 import {
     SynchronizedLyrics,
@@ -51,6 +54,7 @@ export const Lyrics = ({ fadeOutNoLyricsMessage = true, settingsKey = 'default'
     const {
         enableAutoTranslation,
         enableFurigana,
+        enableRomaji,
         preferLocalLyrics,
         translationApiKey,
         translationApiProvider,
@@ -119,6 +123,7 @@ export const Lyrics = ({ fadeOutNoLyricsMessage = true, settingsKey = 'default'
     }, [data, indexToUse, preferLocalLyrics]);
 
     const { data: furiganaConvertedLyrics } = useFuriganaLyrics(lyrics?.lyrics, !!enableFurigana);
+    const { data: romajiConvertedLyrics } = useRomajiLyrics(lyrics?.lyrics, !!enableRomaji);
 
     const displayLyrics = useMemo(() => {
         if (isLyricsDisabled || !lyrics) return null;
@@ -344,12 +349,22 @@ export const Lyrics = ({ fadeOutNoLyricsMessage = true, settingsKey = 'default'
                                     <SynchronizedLyrics
                                         {...(displayLyrics as SynchronizedLyricsProps)}
                                         offsetMs={displayOffsetMs}
+                                        romajiLyrics={
+                                            enableRomaji
+                                                ? (romajiConvertedLyrics as SynchronizedLyricsProps['romajiLyrics'])
+                                                : null
+                                        }
                                         settingsKey={settingsKey}
                                         translatedLyrics={showTranslation ? translatedLyrics : null}
                                     />
                                 ) : (
                                     <UnsynchronizedLyrics
                                         {...(displayLyrics as UnsynchronizedLyricsProps)}
+                                        romajiLyrics={
+                                            enableRomaji
+                                                ? (romajiConvertedLyrics as UnsynchronizedLyricsProps['romajiLyrics'])
+                                                : null
+                                        }
                                         settingsKey={settingsKey}
                                         translatedLyrics={showTranslation ? translatedLyrics : null}
                                     />

src/renderer/features/lyrics/synchronized-lyrics.tsx

@@ -23,6 +23,7 @@ const mpris = isElectron() && utils?.isLinux() ? window.api.mpris : null;
 export interface SynchronizedLyricsProps extends Omit<FullLyricsMetadata, 'lyrics'> {
     lyrics: SynchronizedLyricsArray;
     offsetMs?: number;
+    romajiLyrics?: null | SynchronizedLyricsArray;
     settingsKey?: string;
     style?: React.CSSProperties;
     translatedLyrics?: null | string;
@@ -34,6 +35,7 @@ export const SynchronizedLyrics = ({
     name,
     offsetMs,
     remote,
+    romajiLyrics,
     settingsKey = 'default',
     source,
     style,
@@ -368,10 +370,9 @@ export const SynchronizedLyrics = ({
                             handleSeek(time / 1000);
                         }
                     }}
-                    text={
-                        text +
-                        (translatedLyrics ? `_BREAK_${translatedLyrics.split('\n')[idx]}` : '')
-                    }
+                    romajiText={romajiLyrics?.[idx]?.[1]}
+                    text={text}
+                    translatedText={translatedLyrics?.split('\n')[idx]}
                 />
             ))}
         </div>

src/renderer/features/lyrics/unsynchronized-lyrics.tsx

@@ -8,6 +8,7 @@ import { FullLyricsMetadata } from '/@/shared/types/domain-types';
 
 export interface UnsynchronizedLyricsProps extends Omit<FullLyricsMetadata, 'lyrics'> {
     lyrics: string;
+    romajiLyrics?: null | string;
     settingsKey?: string;
     translatedLyrics?: null | string;
 }
@@ -17,6 +18,7 @@ export const UnsynchronizedLyrics = ({
     lyrics,
     name,
     remote,
+    romajiLyrics,
     settingsKey = 'default',
     source,
     translatedLyrics,
@@ -42,6 +44,10 @@ export const UnsynchronizedLyrics = ({
         return translatedLyrics ? translatedLyrics.split('\n') : [];
     }, [translatedLyrics]);
 
+    const romajiLines = useMemo(() => {
+        return romajiLyrics ? romajiLyrics.split('\n') : [];
+    }, [romajiLyrics]);
+
     return (
         <div className={styles.container} style={{ gap: `${settings.gapUnsync}px` }}>
             {settings.showProvider && source && (
@@ -67,7 +73,9 @@ export const UnsynchronizedLyrics = ({
                     fontSize={settings.fontSizeUnsync}
                     id={`lyric-${idx}`}
                     key={idx}
-                    text={text + (translatedLines[idx] ? `_BREAK_${translatedLines[idx]}` : '')}
+                    romajiText={romajiLines[idx]}
+                    text={text}
+                    translatedText={translatedLines[idx]}
                 />
             ))}
         </div>

src/renderer/features/player/audio-player/engine/mpv-player-engine.tsx

@@ -68,9 +68,13 @@ export const MpvPlayerEngine = (props: MpvPlayerEngineProps) => {
         };
 
         eventEmitter.on('MPV_RELOAD', handleMpvReload);
+        // The main process notifies us after the OS resumes from sleep, since the
+        // stream mpv had open is likely on a now-dead connection.
+        mpvPlayerListener?.rendererMpvReconnect(handleMpvReload);
 
         return () => {
             eventEmitter.off('MPV_RELOAD', handleMpvReload);
+            ipc?.removeAllListeners('renderer-mpv-reconnect');
         };
     }, []);
 

src/renderer/features/settings/components/general/lyric-settings.tsx

@@ -107,6 +107,20 @@ export const LyricSettings = memo(() => {
             isHidden: !isElectron(),
             title: t('setting.enableFurigana'),
         },
+        {
+            control: (
+                <Switch
+                    aria-label="Enable romaji generation"
+                    defaultChecked={settings.enableRomaji}
+                    onChange={(e) => updateSetting({ enableRomaji: e.currentTarget.checked })}
+                />
+            ),
+            description: t('setting.enableRomaji', {
+                context: 'description',
+            }),
+            isHidden: !isElectron(),
+            title: t('setting.enableRomaji'),
+        },
         {
             control: (
                 <Switch

src/renderer/store/settings.store.ts

@@ -578,6 +578,7 @@ const LyricsSettingsSchema = z.object({
     enableAutoTranslation: z.boolean(),
     enableFurigana: z.boolean().optional(),
     enableNeteaseTranslation: z.boolean(),
+    enableRomaji: z.boolean().optional(),
     fetch: z.boolean(),
     follow: z.boolean(),
     preferLocalLyrics: z.boolean(),
@@ -1848,6 +1849,7 @@ const initialState: SettingsState = {
         enableAutoTranslation: false,
         enableFurigana: false,
         enableNeteaseTranslation: false,
+        enableRomaji: false,
         fetch: true,
         follow: true,
         preferLocalLyrics: true,