Flutter Lyric는 Flutter 애플리케이션용으로 사용할 수 있는 유연한 음악 가사 뷰어로, 실시간 가사 하이라이트, 번역된 가사 지원, 부드러운 애니메이션 및 사용자 정의 가능한 UI 컴포넌트를 제공합니다. LRC 형식과 같은 가사 파일을 효율적으로 파싱하여 오디오 재생과 동기화하여 표시합니다. 음악 앱에 적합하며, 다양한 플랫폼에서 시각적으로 매력적이고 상호작용 가능한 가사 표시를 통해 사용자 경험을 향상시킵니다.
English Overview flutter_lyric is a Flutter toolkit for immersive lyric presentation. It ships smooth scrolling, dynamic highlighting, translation/word-by-word rendering, touch selection, masking, and extensive styling hooks so you can build player-grade lyric experiences in minutes.
This README targets the brand-new 3.0.0 release and explains the rewritten rendering pipeline, composable mixins, and the unified LyricController API.
✨ 核心特性 · Highlights
中文
🔥 渐变/颜色高亮:根据播放进度实时推进高亮宽度,可叠加渐变与尾部淡出
🌍 主/副歌词:同屏展示翻译或音译文本,行距与样式完全可调
🌀 平滑滚动:多段滚动时长映射、惯性与自定义锚点,避免跳动
🎯 触摸交互:拖拽选择、点击行、自动恢复、高亮锚点指示
🎨 高度可定制:LyricStyle 暴露 30+ 参数,可快速打造品牌化主题
📦 内置解析:默认支持 .lrc、.qrc 与 .yrc,可注入自定义解析器
🧱 Mixins 设计:滚动、遮罩、行切换、高亮逻辑模块化,方便二次开发
English
🔥 Gradient or solid highlights tied to playback progress with optional trailing fade
🌍 Primary + secondary lyrics for translations or romanization with independent spacing/styles
🌀 Smooth scrolling with distance-based duration mapping, inertia, and configurable anchors
🎯 Touch interactions for scrubbing, tapping, auto-resume, and anchor indicators
🎨 Deep customization via 30+ LyricStyle parameters to match any visual identity
📦 Built-in parsers for .lrc, .qrc, and .yrc, plus hooks for custom formats
🧱 Mixin-based architecture so scroll, mask, switch, and highlight logic can be recomposed
🚀 安装 · Installation
中文
在项目的 pubspec.yaml 中加入 flutter_lyric: ^3.0.0
执行 flutter pub get 拉取依赖
English
Add flutter_lyric: ^3.0.0 to your project's pubspec.yaml
English loadLyric auto-detects .lrc, .qrc, and .yrc (Netease Cloud Music word-by-word plaintext) and accepts an optional translation string that is aligned by timestamp. For custom formats, implement LyricParse or build your own LyricModel.
final customModel = CustomParser().parseRaw(rawLyric);
controller.loadLyricModel(customModel);
English
Use LrcToQrcUtil.convert to convert LRC format to QRC format for word-by-word gradient highlighting. You must provide either the last line duration (lastDuration) or the total song duration (totalDuration).
LyricWidget is merged into LyricView, and LyricController becomes the single source of truth
Previous changeUI/LyricUI hooks are replaced by the more capable LyricStyle
Touch/scroll callbacks now flow through LyricEvent and setOnTapLineCallback
Word-level highlight, translation rows, and masks are built in—custom painters are rarely needed
Style control change: Use LyricView.style parameter instead of controller.setStyle(), aligning with Flutter widget patterns and enabling optimized style change detection
🧪 示例与调试 · Examples & Debugging
example/lib/main.dart
🤝 贡献 · Contributing
中文
欢迎通过 Issue / PR 分享新功能、修复或示例。提交前请运行 flutter test 并附上动图/截图说明效果。
English
Contributions via issues or pull requests are welcome. Please run flutter test before submitting and include screenshots or gifs when possible.
📄 许可证 · License
中文
项目基于 MIT License 发布,可自由商用,欢迎在产品中标注 “Powered by flutter_lyric”。
English
Released under the MIT License. Commercial use is allowed—giving credit such as “Powered by flutter_lyric” is appreciated.