feat: lyrics provider extensions, configurable lyrics cascade, and iOS method channel parity

Add lyrics_provider as a new extension type alongside metadata_provider and
download_provider. Extensions implementing fetchLyrics() are called before
built-in providers, giving user-installed extensions highest priority.

Built-in lyrics cascade is now configurable from Download Settings:
  - Reorderable provider list (LRCLIB, Musixmatch, Netease, Apple Music, QQ Music)
  - Per-provider options: Netease translation/romanization, Apple/QQ multi-person
    word-by-word speaker tags, Musixmatch language code
  - Provider order and options synced to Go backend on app start and on change

Go backend changes:
  - New lyrics_provider manifest type with validation (extension_manifest.go)
  - ExtensionProviderWrapper.FetchLyrics() with Goja JS bridge (extension_providers.go)
  - Configurable SetLyricsProviderOrder/GetLyricsProviderOrder cascade (lyrics.go)
  - LyricsFetchOptions struct for per-provider settings (lyrics.go)
  - Extracted tryLRCLIB() helper, randomized LRCLIB User-Agent (lyrics.go)
  - Refactored msToLRCTimestamp to separate msToLRCTimestampInline (lyrics.go)
  - New provider source files: lyrics_apple.go, lyrics_musixmatch.go,
    lyrics_netease.go, lyrics_qqmusic.go
  - JSON export functions for lyrics settings (exports.go)
  - hasLyricsProvider field in extension manager JSON output

Platform channels:
  - Android (MainActivity.kt): setLyricsProviders, getLyricsProviders,
    getAvailableLyricsProviders, setLyricsFetchOptions, getLyricsFetchOptions
  - iOS (AppDelegate.swift): same 5 method channel handlers for iOS parity

Flutter side:
  - Extension model: hasLyricsProvider field + Lyrics Provider capability badge
  - Settings model: lyricsProviders, lyricsIncludeTranslationNetease,
    lyricsIncludeRomanizationNetease, lyricsMultiPersonWordByWord,
    musixmatchLanguage fields with generated serialization
  - Settings provider: setters + _syncLyricsSettingsToBackend()
  - Download settings UI: provider picker, toggle switches, language picker
  - Platform bridge: lyrics provider/options methods

Docs: lyrics provider extension documentation in site/docs.html
CHANGELOG: updated with lyrics provider and search feature entries

lib/models/settings.dart

@@ -56,6 +56,18 @@ class AppSettings {
   final bool
   hasCompletedTutorial; // Track if user has completed the app tutorial
 
+  // Lyrics Provider Settings
+  final List<String>
+  lyricsProviders; // Ordered list of enabled lyrics provider IDs
+  final bool
+  lyricsIncludeTranslationNetease; // Append translated lyrics (Netease)
+  final bool
+  lyricsIncludeRomanizationNetease; // Append romanized lyrics (Netease)
+  final bool
+  lyricsMultiPersonWordByWord; // Enable v1/v2 + [bg:] tags for Apple/QQ syllable lyrics
+  final String
+  musixmatchLanguage; // Optional ISO language code for Musixmatch localized lyrics
+
   const AppSettings({
     this.defaultService = 'tidal',
     this.audioQuality = 'LOSSLESS',
@@ -100,6 +112,12 @@ class AppSettings {
     this.localLibraryShowDuplicates = true,
     // Tutorial default
     this.hasCompletedTutorial = false,
+    // Lyrics providers default order
+    this.lyricsProviders = const ['lrclib', 'musixmatch', 'netease', 'apple_music', 'qqmusic'],
+    this.lyricsIncludeTranslationNetease = false,
+    this.lyricsIncludeRomanizationNetease = false,
+    this.lyricsMultiPersonWordByWord = true,
+    this.musixmatchLanguage = '',
   });
 
   AppSettings copyWith({
@@ -147,6 +165,12 @@ class AppSettings {
     bool? localLibraryShowDuplicates,
     // Tutorial
     bool? hasCompletedTutorial,
+    // Lyrics providers
+    List<String>? lyricsProviders,
+    bool? lyricsIncludeTranslationNetease,
+    bool? lyricsIncludeRomanizationNetease,
+    bool? lyricsMultiPersonWordByWord,
+    String? musixmatchLanguage,
   }) {
     return AppSettings(
       defaultService: defaultService ?? this.defaultService,
@@ -202,6 +226,15 @@ class AppSettings {
           localLibraryShowDuplicates ?? this.localLibraryShowDuplicates,
       // Tutorial
       hasCompletedTutorial: hasCompletedTutorial ?? this.hasCompletedTutorial,
+      // Lyrics providers
+      lyricsProviders: lyricsProviders ?? this.lyricsProviders,
+      lyricsIncludeTranslationNetease:
+          lyricsIncludeTranslationNetease ?? this.lyricsIncludeTranslationNetease,
+      lyricsIncludeRomanizationNetease:
+          lyricsIncludeRomanizationNetease ?? this.lyricsIncludeRomanizationNetease,
+      lyricsMultiPersonWordByWord:
+          lyricsMultiPersonWordByWord ?? this.lyricsMultiPersonWordByWord,
+      musixmatchLanguage: musixmatchLanguage ?? this.musixmatchLanguage,
     );
   }
 

lib/models/settings.g.dart

@@ -53,50 +53,68 @@ AppSettings _$AppSettingsFromJson(Map<String, dynamic> json) => AppSettings(
   localLibraryShowDuplicates:
       json['localLibraryShowDuplicates'] as bool? ?? true,
   hasCompletedTutorial: json['hasCompletedTutorial'] as bool? ?? false,
+  lyricsProviders:
+      (json['lyricsProviders'] as List<dynamic>?)
+          ?.map((e) => e as String)
+          .toList() ??
+      const ['lrclib', 'musixmatch', 'netease', 'apple_music', 'qqmusic'],
+  lyricsIncludeTranslationNetease:
+      json['lyricsIncludeTranslationNetease'] as bool? ?? false,
+  lyricsIncludeRomanizationNetease:
+      json['lyricsIncludeRomanizationNetease'] as bool? ?? false,
+  lyricsMultiPersonWordByWord:
+      json['lyricsMultiPersonWordByWord'] as bool? ?? true,
+  musixmatchLanguage: json['musixmatchLanguage'] as String? ?? '',
 );
 
-Map<String, dynamic> _$AppSettingsToJson(AppSettings instance) =>
-    <String, dynamic>{
-      'defaultService': instance.defaultService,
-      'audioQuality': instance.audioQuality,
-      'filenameFormat': instance.filenameFormat,
-      'downloadDirectory': instance.downloadDirectory,
-      'storageMode': instance.storageMode,
-      'downloadTreeUri': instance.downloadTreeUri,
-      'autoFallback': instance.autoFallback,
-      'embedLyrics': instance.embedLyrics,
-      'maxQualityCover': instance.maxQualityCover,
-      'isFirstLaunch': instance.isFirstLaunch,
-      'concurrentDownloads': instance.concurrentDownloads,
-      'checkForUpdates': instance.checkForUpdates,
-      'updateChannel': instance.updateChannel,
-      'hasSearchedBefore': instance.hasSearchedBefore,
-      'folderOrganization': instance.folderOrganization,
-      'useAlbumArtistForFolders': instance.useAlbumArtistForFolders,
-      'usePrimaryArtistOnly': instance.usePrimaryArtistOnly,
-      'filterContributingArtistsInAlbumArtist':
-          instance.filterContributingArtistsInAlbumArtist,
-      'historyViewMode': instance.historyViewMode,
-      'historyFilterMode': instance.historyFilterMode,
-      'askQualityBeforeDownload': instance.askQualityBeforeDownload,
-      'spotifyClientId': instance.spotifyClientId,
-      'spotifyClientSecret': instance.spotifyClientSecret,
-      'useCustomSpotifyCredentials': instance.useCustomSpotifyCredentials,
-      'metadataSource': instance.metadataSource,
-      'enableLogging': instance.enableLogging,
-      'useExtensionProviders': instance.useExtensionProviders,
-      'searchProvider': instance.searchProvider,
-      'separateSingles': instance.separateSingles,
-      'albumFolderStructure': instance.albumFolderStructure,
-      'showExtensionStore': instance.showExtensionStore,
-      'locale': instance.locale,
-      'lyricsMode': instance.lyricsMode,
-      'tidalHighFormat': instance.tidalHighFormat,
-      'useAllFilesAccess': instance.useAllFilesAccess,
-      'autoExportFailedDownloads': instance.autoExportFailedDownloads,
-      'downloadNetworkMode': instance.downloadNetworkMode,
-      'localLibraryEnabled': instance.localLibraryEnabled,
-      'localLibraryPath': instance.localLibraryPath,
-      'localLibraryShowDuplicates': instance.localLibraryShowDuplicates,
-      'hasCompletedTutorial': instance.hasCompletedTutorial,
-    };
+Map<String, dynamic> _$AppSettingsToJson(
+  AppSettings instance,
+) => <String, dynamic>{
+  'defaultService': instance.defaultService,
+  'audioQuality': instance.audioQuality,
+  'filenameFormat': instance.filenameFormat,
+  'downloadDirectory': instance.downloadDirectory,
+  'storageMode': instance.storageMode,
+  'downloadTreeUri': instance.downloadTreeUri,
+  'autoFallback': instance.autoFallback,
+  'embedLyrics': instance.embedLyrics,
+  'maxQualityCover': instance.maxQualityCover,
+  'isFirstLaunch': instance.isFirstLaunch,
+  'concurrentDownloads': instance.concurrentDownloads,
+  'checkForUpdates': instance.checkForUpdates,
+  'updateChannel': instance.updateChannel,
+  'hasSearchedBefore': instance.hasSearchedBefore,
+  'folderOrganization': instance.folderOrganization,
+  'useAlbumArtistForFolders': instance.useAlbumArtistForFolders,
+  'usePrimaryArtistOnly': instance.usePrimaryArtistOnly,
+  'filterContributingArtistsInAlbumArtist':
+      instance.filterContributingArtistsInAlbumArtist,
+  'historyViewMode': instance.historyViewMode,
+  'historyFilterMode': instance.historyFilterMode,
+  'askQualityBeforeDownload': instance.askQualityBeforeDownload,
+  'spotifyClientId': instance.spotifyClientId,
+  'spotifyClientSecret': instance.spotifyClientSecret,
+  'useCustomSpotifyCredentials': instance.useCustomSpotifyCredentials,
+  'metadataSource': instance.metadataSource,
+  'enableLogging': instance.enableLogging,
+  'useExtensionProviders': instance.useExtensionProviders,
+  'searchProvider': instance.searchProvider,
+  'separateSingles': instance.separateSingles,
+  'albumFolderStructure': instance.albumFolderStructure,
+  'showExtensionStore': instance.showExtensionStore,
+  'locale': instance.locale,
+  'lyricsMode': instance.lyricsMode,
+  'tidalHighFormat': instance.tidalHighFormat,
+  'useAllFilesAccess': instance.useAllFilesAccess,
+  'autoExportFailedDownloads': instance.autoExportFailedDownloads,
+  'downloadNetworkMode': instance.downloadNetworkMode,
+  'localLibraryEnabled': instance.localLibraryEnabled,
+  'localLibraryPath': instance.localLibraryPath,
+  'localLibraryShowDuplicates': instance.localLibraryShowDuplicates,
+  'hasCompletedTutorial': instance.hasCompletedTutorial,
+  'lyricsProviders': instance.lyricsProviders,
+  'lyricsIncludeTranslationNetease': instance.lyricsIncludeTranslationNetease,
+  'lyricsIncludeRomanizationNetease': instance.lyricsIncludeRomanizationNetease,
+  'lyricsMultiPersonWordByWord': instance.lyricsMultiPersonWordByWord,
+  'musixmatchLanguage': instance.musixmatchLanguage,
+};

lib/providers/extension_provider.dart

@@ -26,6 +26,7 @@ class Extension {
   final List<QualityOption> qualityOptions;
   final bool hasMetadataProvider;
   final bool hasDownloadProvider;
+  final bool hasLyricsProvider;
   final bool skipMetadataEnrichment; // If true, use metadata from extension instead of enriching
   final SearchBehavior? searchBehavior;
   final URLHandler? urlHandler;
@@ -49,6 +50,7 @@ class Extension {
     this.qualityOptions = const [],
     this.hasMetadataProvider = false,
     this.hasDownloadProvider = false,
+    this.hasLyricsProvider = false,
     this.skipMetadataEnrichment = false,
     this.searchBehavior,
     this.urlHandler,
@@ -78,6 +80,7 @@ class Extension {
           .toList() ?? [],
       hasMetadataProvider: json['has_metadata_provider'] as bool? ?? false,
       hasDownloadProvider: json['has_download_provider'] as bool? ?? false,
+      hasLyricsProvider: json['has_lyrics_provider'] as bool? ?? false,
       skipMetadataEnrichment: json['skip_metadata_enrichment'] as bool? ?? false,
       searchBehavior: json['search_behavior'] != null 
           ? SearchBehavior.fromJson(json['search_behavior'] as Map<String, dynamic>)
@@ -111,6 +114,7 @@ class Extension {
     List<QualityOption>? qualityOptions,
     bool? hasMetadataProvider,
     bool? hasDownloadProvider,
+    bool? hasLyricsProvider,
     bool? skipMetadataEnrichment,
     SearchBehavior? searchBehavior,
     URLHandler? urlHandler,
@@ -134,6 +138,7 @@ class Extension {
       qualityOptions: qualityOptions ?? this.qualityOptions,
       hasMetadataProvider: hasMetadataProvider ?? this.hasMetadataProvider,
       hasDownloadProvider: hasDownloadProvider ?? this.hasDownloadProvider,
+      hasLyricsProvider: hasLyricsProvider ?? this.hasLyricsProvider,
       skipMetadataEnrichment: skipMetadataEnrichment ?? this.skipMetadataEnrichment,
       searchBehavior: searchBehavior ?? this.searchBehavior,
       urlHandler: urlHandler ?? this.urlHandler,

lib/providers/settings_provider.dart

@@ -39,6 +39,23 @@ class SettingsNotifier extends Notifier<AppSettings> {
     _applySpotifyCredentials();
 
     LogBuffer.loggingEnabled = state.enableLogging;
+
+    _syncLyricsSettingsToBackend();
+  }
+
+  void _syncLyricsSettingsToBackend() {
+    PlatformBridge.setLyricsProviders(state.lyricsProviders).catchError((e) {
+      _log.w('Failed to sync lyrics providers to backend: $e');
+    });
+
+    PlatformBridge.setLyricsFetchOptions({
+      'include_translation_netease': state.lyricsIncludeTranslationNetease,
+      'include_romanization_netease': state.lyricsIncludeRomanizationNetease,
+      'multi_person_word_by_word': state.lyricsMultiPersonWordByWord,
+      'musixmatch_language': state.musixmatchLanguage,
+    }).catchError((e) {
+      _log.w('Failed to sync lyrics fetch options to backend: $e');
+    });
   }
 
   Future<void> _runMigrations(SharedPreferences prefs) async {
@@ -188,6 +205,36 @@ class SettingsNotifier extends Notifier<AppSettings> {
     }
   }
 
+  void setLyricsProviders(List<String> providers) {
+    state = state.copyWith(lyricsProviders: providers);
+    _saveSettings();
+    _syncLyricsSettingsToBackend();
+  }
+
+  void setLyricsIncludeTranslationNetease(bool enabled) {
+    state = state.copyWith(lyricsIncludeTranslationNetease: enabled);
+    _saveSettings();
+    _syncLyricsSettingsToBackend();
+  }
+
+  void setLyricsIncludeRomanizationNetease(bool enabled) {
+    state = state.copyWith(lyricsIncludeRomanizationNetease: enabled);
+    _saveSettings();
+    _syncLyricsSettingsToBackend();
+  }
+
+  void setLyricsMultiPersonWordByWord(bool enabled) {
+    state = state.copyWith(lyricsMultiPersonWordByWord: enabled);
+    _saveSettings();
+    _syncLyricsSettingsToBackend();
+  }
+
+  void setMusixmatchLanguage(String languageCode) {
+    state = state.copyWith(musixmatchLanguage: languageCode.trim().toLowerCase());
+    _saveSettings();
+    _syncLyricsSettingsToBackend();
+  }
+
   void setMaxQualityCover(bool enabled) {
     state = state.copyWith(maxQualityCover: enabled);
     _saveSettings();

lib/screens/settings/download_settings_page.dart

@@ -279,6 +279,61 @@ class _DownloadSettingsPageState extends ConsumerState<DownloadSettingsPage> {
                       ref,
                       settings.lyricsMode,
                     ),
+                  ),
+                  SettingsItem(
+                    icon: Icons.source_outlined,
+                    title: 'Lyrics Providers',
+                    subtitle: _getLyricsProvidersSubtitle(settings.lyricsProviders),
+                    onTap: () => _showLyricsProvidersPicker(
+                      context,
+                      ref,
+                      settings.lyricsProviders,
+                    ),
+                  ),
+                  SettingsSwitchItem(
+                    icon: Icons.translate_outlined,
+                    title: 'Netease: Include Translation',
+                    subtitle: settings.lyricsIncludeTranslationNetease
+                        ? 'Append translated lyrics when available'
+                        : 'Use original lyrics only',
+                    value: settings.lyricsIncludeTranslationNetease,
+                    onChanged: (value) => ref
+                        .read(settingsProvider.notifier)
+                        .setLyricsIncludeTranslationNetease(value),
+                  ),
+                  SettingsSwitchItem(
+                    icon: Icons.text_fields_outlined,
+                    title: 'Netease: Include Romanization',
+                    subtitle: settings.lyricsIncludeRomanizationNetease
+                        ? 'Append romanized lyrics when available'
+                        : 'Disabled',
+                    value: settings.lyricsIncludeRomanizationNetease,
+                    onChanged: (value) => ref
+                        .read(settingsProvider.notifier)
+                        .setLyricsIncludeRomanizationNetease(value),
+                  ),
+                  SettingsSwitchItem(
+                    icon: Icons.record_voice_over_outlined,
+                    title: 'Apple/QQ Multi-Person Word-by-Word',
+                    subtitle: settings.lyricsMultiPersonWordByWord
+                        ? 'Enable v1/v2 speaker and [bg:] tags'
+                        : 'Simplified word-by-word formatting',
+                    value: settings.lyricsMultiPersonWordByWord,
+                    onChanged: (value) => ref
+                        .read(settingsProvider.notifier)
+                        .setLyricsMultiPersonWordByWord(value),
+                  ),
+                  SettingsItem(
+                    icon: Icons.language_outlined,
+                    title: 'Musixmatch Language',
+                    subtitle: settings.musixmatchLanguage.isEmpty
+                        ? 'Auto (original)'
+                        : settings.musixmatchLanguage.toUpperCase(),
+                    onTap: () => _showMusixmatchLanguagePicker(
+                      context,
+                      ref,
+                      settings.musixmatchLanguage,
+                    ),
                     showDivider: false,
                   ),
                 ],
@@ -1183,6 +1238,278 @@ class _DownloadSettingsPageState extends ConsumerState<DownloadSettingsPage> {
     );
   }
 
+  static const _providerDisplayNames = <String, String>{
+    'lrclib': 'LRCLIB',
+    'netease': 'Netease',
+    'musixmatch': 'Musixmatch',
+    'apple_music': 'Apple Music',
+    'qqmusic': 'QQ Music',
+  };
+
+  static const _providerDescriptions = <String, String>{
+    'lrclib': 'Open-source synced lyrics database',
+    'netease': 'NetEase Cloud Music (good for Asian songs)',
+    'musixmatch': 'Largest lyrics database (multi-language)',
+    'apple_music': 'Word-by-word synced lyrics (via proxy)',
+    'qqmusic': 'QQ Music (good for Chinese songs, via proxy)',
+  };
+
+  String _getLyricsProvidersSubtitle(List<String> providers) {
+    if (providers.isEmpty) return 'None enabled';
+    return providers
+        .map((p) => _providerDisplayNames[p] ?? p)
+        .join(' > ');
+  }
+
+  void _showLyricsProvidersPicker(
+    BuildContext context,
+    WidgetRef ref,
+    List<String> currentProviders,
+  ) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final allProviders = ['lrclib', 'netease', 'musixmatch', 'apple_music', 'qqmusic'];
+
+    // Work with a mutable copy
+    final selectedProviders = List<String>.from(currentProviders);
+
+    showModalBottomSheet(
+      context: context,
+      backgroundColor: colorScheme.surfaceContainerHigh,
+      shape: const RoundedRectangleBorder(
+        borderRadius: BorderRadius.vertical(top: Radius.circular(28)),
+      ),
+      isScrollControlled: true,
+      builder: (context) => StatefulBuilder(
+        builder: (context, setLocalState) => SafeArea(
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            crossAxisAlignment: CrossAxisAlignment.start,
+            children: [
+              Padding(
+                padding: const EdgeInsets.fromLTRB(24, 24, 24, 8),
+                child: Text(
+                  'Lyrics Providers',
+                  style: Theme.of(context).textTheme.titleLarge?.copyWith(
+                    fontWeight: FontWeight.bold,
+                  ),
+                ),
+              ),
+              Padding(
+                padding: const EdgeInsets.fromLTRB(24, 0, 24, 8),
+                child: Text(
+                  'Enable/disable and reorder lyrics sources. Providers are tried top-to-bottom until lyrics are found.',
+                  style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                    color: colorScheme.onSurfaceVariant,
+                  ),
+                ),
+              ),
+              // Reorderable list of providers
+              ...allProviders.map((providerId) {
+                final isEnabled = selectedProviders.contains(providerId);
+                final displayName = _providerDisplayNames[providerId] ?? providerId;
+                final description = _providerDescriptions[providerId] ?? '';
+                final orderIndex = selectedProviders.indexOf(providerId);
+
+                return CheckboxListTile(
+                  title: Row(
+                    children: [
+                      if (isEnabled)
+                        Padding(
+                          padding: const EdgeInsets.only(right: 8),
+                          child: CircleAvatar(
+                            radius: 12,
+                            backgroundColor: colorScheme.primaryContainer,
+                            child: Text(
+                              '${orderIndex + 1}',
+                              style: TextStyle(
+                                fontSize: 12,
+                                fontWeight: FontWeight.bold,
+                                color: colorScheme.onPrimaryContainer,
+                              ),
+                            ),
+                          ),
+                        ),
+                      Text(displayName),
+                    ],
+                  ),
+                  subtitle: Text(description),
+                  value: isEnabled,
+                  onChanged: (bool? value) {
+                    setLocalState(() {
+                      if (value == true) {
+                        selectedProviders.add(providerId);
+                      } else {
+                        selectedProviders.remove(providerId);
+                      }
+                    });
+                    ref.read(settingsProvider.notifier).setLyricsProviders(
+                      List<String>.from(selectedProviders),
+                    );
+                  },
+                );
+              }),
+              // Move up/down hint
+              Padding(
+                padding: const EdgeInsets.fromLTRB(24, 8, 24, 4),
+                child: Text(
+                  'Priority order (tap to move):',
+                  style: Theme.of(context).textTheme.labelMedium?.copyWith(
+                    color: colorScheme.onSurfaceVariant,
+                  ),
+                ),
+              ),
+              // Show enabled providers with move controls
+              ...selectedProviders.asMap().entries.map((entry) {
+                final index = entry.key;
+                final providerId = entry.value;
+                final displayName = _providerDisplayNames[providerId] ?? providerId;
+
+                return ListTile(
+                  dense: true,
+                  leading: CircleAvatar(
+                    radius: 14,
+                    backgroundColor: colorScheme.primary,
+                    child: Text(
+                      '${index + 1}',
+                      style: TextStyle(
+                        fontSize: 13,
+                        fontWeight: FontWeight.bold,
+                        color: colorScheme.onPrimary,
+                      ),
+                    ),
+                  ),
+                  title: Text(displayName),
+                  trailing: Row(
+                    mainAxisSize: MainAxisSize.min,
+                    children: [
+                      if (index > 0)
+                        IconButton(
+                          icon: const Icon(Icons.arrow_upward, size: 20),
+                          onPressed: () {
+                            setLocalState(() {
+                              selectedProviders.removeAt(index);
+                              selectedProviders.insert(index - 1, providerId);
+                            });
+                            ref.read(settingsProvider.notifier).setLyricsProviders(
+                              List<String>.from(selectedProviders),
+                            );
+                          },
+                        ),
+                      if (index < selectedProviders.length - 1)
+                        IconButton(
+                          icon: const Icon(Icons.arrow_downward, size: 20),
+                          onPressed: () {
+                            setLocalState(() {
+                              selectedProviders.removeAt(index);
+                              selectedProviders.insert(index + 1, providerId);
+                            });
+                            ref.read(settingsProvider.notifier).setLyricsProviders(
+                              List<String>.from(selectedProviders),
+                            );
+                          },
+                        ),
+                    ],
+                  ),
+                );
+              }),
+              const SizedBox(height: 16),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+
+  String _normalizeMusixmatchLanguage(String value) {
+    final normalized = value.trim().toLowerCase();
+    return normalized.replaceAll(RegExp(r'[^a-z0-9\-_]'), '');
+  }
+
+  void _showMusixmatchLanguagePicker(
+    BuildContext context,
+    WidgetRef ref,
+    String currentLanguage,
+  ) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final controller = TextEditingController(text: currentLanguage);
+
+    showModalBottomSheet(
+      context: context,
+      backgroundColor: colorScheme.surfaceContainerHigh,
+      shape: const RoundedRectangleBorder(
+        borderRadius: BorderRadius.vertical(top: Radius.circular(28)),
+      ),
+      isScrollControlled: true,
+      builder: (context) => Padding(
+        padding: EdgeInsets.only(
+          left: 24,
+          right: 24,
+          top: 24,
+          bottom: 24 + MediaQuery.of(context).viewInsets.bottom,
+        ),
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Text(
+              'Musixmatch Language',
+              style: Theme.of(context).textTheme.titleLarge?.copyWith(
+                fontWeight: FontWeight.bold,
+              ),
+            ),
+            const SizedBox(height: 8),
+            Text(
+              'Set preferred language code (example: en, es, ja). Leave empty for auto.',
+              style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                color: colorScheme.onSurfaceVariant,
+              ),
+            ),
+            const SizedBox(height: 16),
+            TextField(
+              controller: controller,
+              textInputAction: TextInputAction.done,
+              decoration: const InputDecoration(
+                labelText: 'Language code',
+                hintText: 'auto / en / es / ja',
+              ),
+            ),
+            const SizedBox(height: 16),
+            Row(
+              mainAxisAlignment: MainAxisAlignment.end,
+              children: [
+                TextButton(
+                  onPressed: () => Navigator.pop(context),
+                  child: Text(context.l10n.dialogCancel),
+                ),
+                const SizedBox(width: 8),
+                TextButton(
+                  onPressed: () {
+                    ref.read(settingsProvider.notifier).setMusixmatchLanguage('');
+                    Navigator.pop(context);
+                  },
+                  child: const Text('Auto'),
+                ),
+                const SizedBox(width: 8),
+                FilledButton(
+                  onPressed: () {
+                    final normalized = _normalizeMusixmatchLanguage(
+                      controller.text,
+                    );
+                    ref
+                        .read(settingsProvider.notifier)
+                        .setMusixmatchLanguage(normalized);
+                    Navigator.pop(context);
+                  },
+                  child: Text(context.l10n.dialogSave),
+                ),
+              ],
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
   String _getTidalHighFormatLabel(String format) {
     switch (format) {
       case 'mp3_320':

lib/screens/settings/extension_detail_page.dart

@@ -218,6 +218,11 @@ class _ExtensionDetailPageState extends ConsumerState<ExtensionDetailPage> {
                   title: context.l10n.extensionDownloadProvider,
                   enabled: extension.hasDownloadProvider,
                 ),
+                _CapabilityItem(
+                  icon: Icons.lyrics,
+                  title: context.l10n.extensionLyricsProvider,
+                  enabled: extension.hasLyricsProvider,
+                ),
                 _CapabilityItem(
                   icon: Icons.manage_search,
                   title: context.l10n.extensionsSearchProvider,

lib/services/platform_bridge.dart

@@ -332,6 +332,44 @@ class PlatformBridge {
     return jsonDecode(result as String) as Map<String, dynamic>;
   }
 
+  // ==================== LYRICS PROVIDER SETTINGS ====================
+
+  /// Sets the lyrics provider order. Providers not in the list are disabled.
+  static Future<void> setLyricsProviders(List<String> providers) async {
+    final providersJSON = jsonEncode(providers);
+    await _channel.invokeMethod('setLyricsProviders', {
+      'providers_json': providersJSON,
+    });
+  }
+
+  /// Returns the current lyrics provider order.
+  static Future<List<String>> getLyricsProviders() async {
+    final result = await _channel.invokeMethod('getLyricsProviders');
+    final List<dynamic> decoded = jsonDecode(result as String) as List<dynamic>;
+    return decoded.cast<String>();
+  }
+
+  /// Returns metadata about all available lyrics providers.
+  static Future<List<Map<String, dynamic>>> getAvailableLyricsProviders() async {
+    final result = await _channel.invokeMethod('getAvailableLyricsProviders');
+    final List<dynamic> decoded = jsonDecode(result as String) as List<dynamic>;
+    return decoded.cast<Map<String, dynamic>>();
+  }
+
+  /// Sets advanced lyrics fetch options used by provider-specific integrations.
+  static Future<void> setLyricsFetchOptions(Map<String, dynamic> options) async {
+    final optionsJSON = jsonEncode(options);
+    await _channel.invokeMethod('setLyricsFetchOptions', {
+      'options_json': optionsJSON,
+    });
+  }
+
+  /// Returns current advanced lyrics fetch options.
+  static Future<Map<String, dynamic>> getLyricsFetchOptions() async {
+    final result = await _channel.invokeMethod('getLyricsFetchOptions');
+    return jsonDecode(result as String) as Map<String, dynamic>;
+  }
+
   static Future<Map<String, dynamic>> reEnrichFile(
     Map<String, dynamic> request,
   ) async {