# local-music

**Repository Path**: SimanX/local-music

## Basic Information

- **Project Name**: local-music
- **Description**: 本地音乐播放器，可以管理、播放本地音乐
- **Primary Language**: Dart
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-07-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Local Music

一款 Android 本地音乐播放器，基于 Flutter 构建。支持扫描设备中的音频文件、多维度浏览曲库、歌单管理与后台播放，注重流畅的播放体验与清晰的界面层级设计。

[![License: PolyForm Noncommercial 1.0.0](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](LICENSE)

## 特性

### 音乐库

- **本地扫描**：通过 Android MediaStore 扫描 MP3、FLAC、WAV 等常见格式，可配置扫描范围
- **多维度浏览**：歌曲 / 歌单 / 最近播放 / 专辑 / 歌手 / 文件夹六个 Tab，支持搜索与 Tab 记忆
- **SQLite 缓存**：歌曲元数据本地持久化（无外键，歌单通过 `song_ids` 逻辑关联）
- **多曲库管理**：支持创建与切换多个独立曲库

### 播放体验

- **后台播放**：切到后台或锁屏后音乐继续播放
- **系统媒体控制**：通知栏与锁屏界面显示封面、歌名，支持播放/暂停、上一首/下一首、进度拖动
- **迷你播放器**：常驻底部，与详情页、Tab 切换无缝共存
- **播放页**：高斯模糊背景、封面取色、播放队列、播放顺序切换、倍速调节
- **播放页布局**：经典布局 / 歌词优先布局，可切换
- **歌词**：自动匹配同目录 LRC 文件，支持歌词滚动显示
- **睡眠定时**：15 / 30 / 45 / 60 分钟定时停止播放

### 歌单与收藏

- 自定义歌单创建与管理
- 收藏同步至「我的收藏」
- 歌曲批量操作（加入歌单、删除等）

### 外观与设置

- 主题模式：浅色 / 深色 / 跟随系统
- 品牌启动页动画

## 环境要求

- Flutter SDK >= 3.2.0
- Dart SDK >= 3.2.0
- Android SDK（目标平台为 Android）
- 一台 Android 真机或模拟器（推荐真机验证后台播放与锁屏控制）

## 快速开始

```bash
flutter pub get
flutter run
```

首次启动请授予「音频 / 存储」读取权限，然后在设置中扫描音乐库。

## 构建

```bash
# Debug APK
flutter build apk --debug

# Release APK
flutter build apk --release
```

输出路径：`build/app/outputs/flutter-apk/`

## 项目结构

```
lib/
├── app.dart                 # 应用入口与主题
├── core/                    # 导航、主题、常量
├── database/                # SQLite 数据库
├── models/                  # 数据模型
├── providers/               # Riverpod 状态管理
├── screens/                 # 页面
├── services/                # 音频服务、扫描、权限
├── utils/                   # 工具函数
└── widgets/                 # 可复用组件
```

## 技术栈

| 类别 | 依赖 |
|------|------|
| 框架 | Flutter、Riverpod |
| 音频 | just_audio、audio_service、audio_session |
| 本地数据 | on_audio_query、sqflite |
| 其他 | permission_handler、file_picker、palette_generator_plus |

## 开发

### 运行测试

```bash
flutter test
```

## 支持作者

本地音乐是一款免费开源的本地播放器。如果你喜欢这个项目，欢迎通过以下方式支持开发者的持续维护与功能迭代：

- **爱发电**：[https://afdian.com/a/local-music](https://afdian.com/a/local-music)
- **微信收款码**：使用微信扫描下方二维码

![微信收款码](assets/support/wechat_qrcode.png)

## 许可证

本项目采用 [PolyForm Noncommercial License 1.0.0](LICENSE)（非商用许可证）。

**你可以：**

- 自由查看、使用、修改本项目源码
- 在非商用场景下分发本项目或其衍生作品
- 用于个人学习、研究、爱好项目，以及教育、慈善、政府等非营利机构

**你不可以：**

- 将本项目或其衍生作品用于任何商业目的
- 在未保留许可证条款的情况下再分发

如需商用授权，请联系项目维护者。

---

Copyright (c) 2026 [SimanX](https://gitee.com/SimanX)