spotube/LYRICS_PLUGIN_MIGRATION.md

Lyrics Plugin System Migration

This document explains the migration from built-in lyrics to a plugin-based system.

What Changed

Before

• Lyrics providers were built into the main application
• Hard-coded implementations for each service
• Required app updates to add new providers

After

• Lyrics are provided through plugins
• Community can create providers for any service
• No app updates needed for new providers
• Follows the same pattern as audio source plugins

Architecture

┌─────────────────────────────────────────┐
│         Spotube Main App                │
│                                         │
│  ┌───────────────────────────────────┐ │
│  │   Lyrics Plugin Interface         │ │
│  │   (MetadataPluginLyricsEndpoint)  │ │
│  └───────────────────────────────────┘ │
│                  ↓                      │
│  ┌───────────────────────────────────┐ │
│  │   Hetu Script Engine              │ │
│  └───────────────────────────────────┘ │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│      Lyrics Plugin (.smplug)            │
│                                         │
│  - plugin.json (metadata)               │
│  - plugin.out (compiled Hetu bytecode)  │
│  - logo.png (optional)                  │
│                                         │
│  Implements:                            │
│  - search(params) → List<Lyrics>        │
│  - getById(id) → Lyrics?                │
│  - isAvailable() → bool                 │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│      External Lyrics API                │
│  (LrcLib, Musixmatch, Genius, etc.)     │
└─────────────────────────────────────────┘

Main App Changes

Added Files

• lib/services/metadata/endpoints/lyrics.dart - Lyrics endpoint interface
• lib/provider/lyrics_plugin_provider.dart - Riverpod providers for lyrics
• lib/services/lyrics_provider/README.md - Documentation
• LYRICS_PLUGIN_GUIDE.md - Plugin development guide
• LYRICS_PLUGIN_TEMPLATE.md - Template repository structure
• LYRICS_PLUGIN_MIGRATION.md - This file

Modified Files

• lib/models/metadata/plugin.dart - Added lyrics to PluginAbilities enum
• lib/services/metadata/metadata.dart - Added lyrics endpoint initialization

Removed Files

• All built-in lyrics provider implementations (moved to plugins)

Plugin Development

Quick Start

1. Clone template: LYRICS_PLUGIN_TEMPLATE.md
2. Implement Hetu script in src/main.ht
3. Compile: hetu compile src/main.ht -o plugin.out
4. Package: zip plugin.smplug plugin.json plugin.out logo.png
5. Publish on GitHub with releases

Required Methods

class LyricsEndpoint {
  external fun search(Map params) async
  external fun getById(String id) async
  external fun isAvailable() async
}

Data Format

Input (search params):

{
  'trackName': String,
  'artistName': String,
  'albumName': String?,
  'duration': int?  // seconds
}

Output (lyrics):

{
  'uri': String,
  'name': String,
  'lyrics': [
    {
      'time': int,  // milliseconds
      'text': String
    }
  ],
  'rating': int,
  'provider': String
}

Usage in Main App

Get Lyrics Plugin

final plugin = ref.watch(lyricsPluginProvider);

Search Lyrics

final lyrics = await ref.read(lyricsSearchProvider({
  'trackName': 'Song Name',
  'artistName': 'Artist Name',
  'albumName': 'Album Name',
  'duration': Duration(seconds: 180),
}).future);

Get by ID

final lyric = await ref.read(lyricsByIdProvider('lrclib:12345').future);

Plugin Examples

LrcLib Plugin

• Free, open-source
• No API key required
• Repository: Create at spotube-plugin-lrclib-lyrics

Musixmatch Plugin

• Commercial service
• Requires API key
• Repository: Create at spotube-plugin-musixmatch-lyrics

Genius Plugin

• Community lyrics
• Web scraping or API
• Repository: Create at spotube-plugin-genius-lyrics

Benefits

1. Extensibility: Anyone can add new lyrics sources
2. Maintainability: Plugins maintained separately
3. Flexibility: Users choose their preferred provider
4. Privacy: No forced third-party services
5. Community: Encourages community contributions
6. Updates: Plugins update independently

Migration Path for Users

1. Update Spotube to version with plugin support
2. Install lyrics plugin from Settings > Plugins
3. Choose default lyrics provider
4. Existing lyrics cache remains compatible

For Plugin Developers

Resources

• Plugin Guide: LYRICS_PLUGIN_GUIDE.md
• Template: LYRICS_PLUGIN_TEMPLATE.md
• Example: Check assets/plugins/spotube-plugin-youtube-audio/
• Hetu Docs: https://hetu.dev

Testing

1. Compile plugin locally
2. Load in Spotube via file path
3. Test search and getById methods
4. Verify time-sync accuracy
5. Test error handling

Publishing

1. Create GitHub repository
2. Add GitHub Actions for auto-build
3. Create release with .smplug file
4. Users install via repo URL

Support

• Discord: https://discord.gg/spotube
• GitHub: https://github.com/KRTirtho/spotube
• Docs: https://spotube.krtirtho.dev

Future Enhancements

• Multiple provider fallback
• Provider priority settings
• Lyrics caching system
• Offline lyrics support
• User-contributed lyrics
• Lyrics translation plugins
• Karaoke mode plugins