# MiluMusic

**Repository Path**: sunhaiwei/milu-music

## Basic Information

- **Project Name**: MiluMusic
- **Description**: 融合 Flet 与 Craft（工艺/精心打造），体现组件开发的手工感与专业度，简洁易记
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎵 Milu Music — 桌面音乐播放器

基于 [Flet](https://flet.dev) 构建的桌面音乐播放器，使用 [MusicLibrary](https://github.com/2061360308/MusicLibrary) 提供音乐搜索、播放和管理功能。支持深/浅色主题、歌词同步、播放队列、MV 播放等。

## ✨ 功能特性

- **在线音乐搜索** — 支持单曲、专辑、歌手、歌单、MV 多类型搜索
- **在线播放** — 对接 MusicLibrary 音乐 API，搜索即听
- **歌词同步** — LRC 歌词解析与实时高亮，支持滚动跟随
- **播放队列** — 列表循环 / 单曲循环 / 随机播放三种模式
- **MV 播放** — 音乐视频在线播放
- **歌单浏览** — 浏览和查看精选歌单、排行榜、歌手
- **专辑/歌手详情** — 专辑曲目列表、歌手作品与简介
- **深色/浅色主题** — 一键切换，配色跟随 Material 3 设计规范
- **动态封面背景** — 歌词面板/播放栏背景跟随封面主色调平滑过渡
- **自定义字体** — 内置「方正悠题」中文字体（FZYTK）
- **响应式管理布局** — 侧边栏导航 + 顶部搜索栏 + 底部播放栏

## 📸 界面预览

| 首页 | 歌单 | 排行榜 |
|:---:|:---:|:---:|
| ![首页](docs/images/1.png) | ![歌单](docs/images/3.png) | ![排行榜](docs/images/4.png) |

| 歌手 | MV | 歌词封面 |
|:---:|:---:|:---:|
| ![歌手](docs/images/5.png) | ![MV](docs/images/6.png) | ![歌词封面](docs/images/7.png) |

## 🖥️ 页面 / 路由

| 路由 | 页面 | 说明 |
|------|------|------|
| `/` | HomePage | 首页 — 推荐歌单、排行榜、热门歌手、新MV |
| `/search` | SearchPage | 搜索 — 多类型搜索结果展示 |
| `/playlists` | PlaylistsPage | 歌单广场 — 分类浏览与搜索 |
| `/playlist/:id` | PlaylistDetailPage | 歌单详情 — 曲目列表与播放 |
| `/leaderboard` | LeaderboardPage | 排行榜列表 |
| `/leaderboard/:id` | LeaderboardDetailPage | 排行榜详情 |
| `/artists` | ArtistsPage | 歌手列表 — 分类筛选 |
| `/artist/:id` | ArtistDetailPage | 歌手详情 — 热门歌曲/专辑/简介 |
| `/album/:id` | AlbumDetailPage | 专辑详情 — 曲目列表 |
| `/mv` | MVPage | MV 列表 |
| `/mv/:id` | MvDetailPage | MV 播放页 |
| `/user` | UserPage | 用户页面 |
| `/settings` | SettingsPage | 设置页 |

## 🛠️ 技术栈

| 技术 | 说明 |
|------|------|
| [Flet](https://flet.dev) 0.86+ | Python GUI 框架，基于 Flutter 渲染 |
| [flet-audio](https://pypi.org/project/flet-audio/) 0.86+ | 音频播放控件 |
| [flet-charts](https://pypi.org/project/flet-charts/) | 图表控件 |
| [MusicLibrary](https://github.com/2061360308/MusicLibrary) | 音乐 API 封装（第三方开源） |
| Pillow | 封面主色调提取 |
| Python 3.10+ | 开发语言 |
| [uv](https://docs.astral.sh/uv/) | 包管理器 |

## 📋 前置要求

- Python 3.10+
- [uv](https://docs.astral.sh/uv/#installation) 包管理器

**打包为桌面应用（可选）：**

- **Windows**: [Visual Studio 2022](https://visualstudio.microsoft.com/)（勾选「使用 C++ 的桌面开发」工作负载）
- **macOS**: Xcode
- **Linux**: GTK 开发库

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone <repo-url>
cd FletTest
```

### 2. 安装依赖

```bash
uv sync
```

### 3. 运行开发版

桌面应用（Flet 标准入口 `src/main.py`）：

```bash
uv run flet run
```

Web 应用：

```bash
uv run flet run --web
```

## 📦 打包发布

### Windows (.exe)

```bash
uv run flet build windows -v
```

产物在 `build/windows/` 目录下。更多细节见 [Windows 打包指南](https://flet.dev/docs/publish/windows/)。

### macOS (.app)

```bash
uv run flet build macos -v
```

更多细节见 [macOS 打包指南](https://flet.dev/docs/publish/macos/)。

### Linux

```bash
uv run flet build linux -v
```

更多细节见 [Linux 打包指南](https://flet.dev/docs/publish/linux/)。

### Android (.apk / .aab)

```bash
uv run flet build apk -v
```

更多细节见 [Android 打包指南](https://flet.dev/docs/publish/android/)。

### iOS (.ipa)

```bash
uv run flet build ipa -v
```

更多细节见 [iOS 打包指南](https://flet.dev/docs/publish/ios/)。

### Web

```bash
uv run flet build web -v
```

更多细节见 [Web 打包指南](https://flet.dev/docs/publish/web/)。

> **注意**：Windows 打包需安装 Visual Studio 2022 并启用「使用 C++ 的桌面开发」工作负载。其他平台首次构建时会自动下载 Flutter SDK。

## 📁 项目结构

项目采用 Flet 标准 `src/` 布局（`[tool.flet.app] path = "src"`，入口为 `src/main.py`）：

```
MiluMusic/
├── src/                            # 应用源码（Flet 标准布局）
│   ├── main.py                     #   应用入口（Flet 标准启动文件）
│   ├── app.py                      #   Router 定义
│   ├── layout.py                   #   后台布局组件
│   ├── theme.py                    #   配色方案与主题
│   ├── assets/                     #   资源文件（字体、图标）
│   │   ├── FZYTK.TTF               #     自定义中文字体
│   │   ├── icon.png                #     应用图标
│   │   ├── icon.ico                #     Windows 图标
│   │   ├── icon_windows.ico        #     Windows 图标（高清）
│   │   └── splash_android.png      #     Android 启动图
│   ├── components/                 #   可复用组件
│   │   ├── sidebar.py              #     侧边导航栏
│   │   ├── top_bar.py              #     顶部操作栏
│   │   ├── title_bar.py            #     标题栏
│   │   ├── player_bar.py           #     底部播放栏
│   │   ├── now_playing_panel.py    #     播放列表面板
│   │   ├── lyrics_panel.py         #     歌词显示面板
│   │   ├── lyrics_view.py          #     歌词滚动视图
│   │   ├── lyric_backdrop.py       #     歌词遮罩
│   │   ├── queue_backdrop.py       #     队列遮罩
│   │   ├── song_item.py            #     歌曲列表项
│   │   ├── song_row.py             #     歌曲行
│   │   ├── song_list_panel.py      #     歌曲列表面板
│   │   ├── progress_bar.py         #     自定义进度条
│   │   ├── seek_bar.py             #     进度条滑块
│   │   ├── spinning_cover.py       #     旋转封面
│   │   ├── carousel.py             #     轮播图组件
│   │   ├── recommendation_cards.py #     推荐卡片
│   │   ├── hot_song_list.py        #     热门歌曲列表
│   │   ├── media_card.py           #     通用封面卡片
│   │   ├── genre_tags.py           #     分类标签
│   │   └── sidebar_right.py        #     右侧面板
│   ├── pages/                      #   页面组件
│   │   ├── home.py                 #     首页
│   │   ├── search.py               #     搜索页
│   │   ├── playlists.py            #     歌单广场
│   │   ├── playlist_detail.py      #     歌单详情
│   │   ├── leaderboard.py          #     排行榜
│   │   ├── leaderboard_detail.py   #     排行榜详情
│   │   ├── artists.py              #     歌手列表
│   │   ├── artist_detail.py        #     歌手详情
│   │   ├── album_detail.py         #     专辑详情
│   │   ├── mv.py                   #     MV 列表
│   │   ├── mv_detail.py            #     MV 播放
│   │   ├── user.py                 #     用户
│   │   └── settings.py             #     设置
│   ├── services/                   #   服务层
│   │   ├── netease_api.py          #     音乐 API 封装
│   │   └── player_service.py       #     播放服务
│   ├── models/                     #   数据模型（@ft.observable）
│   │   ├── player_state.py         #     播放器状态
│   │   ├── lyrics_state.py         #     歌词状态
│   │   ├── mv_state.py             #     MV 状态
│   │   ├── cover_color_state.py    #     封面主色状态
│   │   ├── playback_position.py    #     播放进度
│   │   ├── playback_queue.py       #     播放队列
│   │   ├── song_info.py            #     歌曲信息
│   │   ├── navigation_state.py     #     导航状态
│   │   └── search_info.py          #     搜索状态
│   ├── core/                       #   核心服务
│   │   ├── audio_service.py        #     音频播放服务
│   │   ├── cover_color.py          #     封面主色提取
│   │   └── settings_store.py       #     设置持久化
│   └── data/                       #   数据层
├── docs/                           # 文档与截图
├── tests/                          # demo 脚本与 pytest 测试
└── pyproject.toml                  # 项目配置与依赖
```

## ⚙️ 配置说明

### `pyproject.toml`

| 配置项 | 值 | 说明 |
|--------|-----|------|
| `[tool.flet.app].path` | `src` | 应用根目录（Flet 标准 src 布局）|
| `[tool.flet].product` | `flettest` | 产品名称 |
| `[tool.flet].org` | `com.mycompany` | 组织标识 |

> 入口为 `src/main.py`，`flet run` / `flet build` 会自动定位。

## 🧪 开发说明

- 项目使用 `@ft.component` 函数组件模式 + `@ft.observable` 响应式数据模型
- 状态管理：模块级 observable 单例，通过 `ft.use_state()` 订阅
- 路由：`ft.Router` + `ft.Route` 声明式路由
- 音频：`flet-audio` 通过 `page.services.append()` 注册
- 歌词面板/播放栏背景：封面主色经 Pillow 提取（`core/cover_color.py`），写入共享 `cover_color_state` 平滑过渡

## 🔗 相关资源

- [Flet 官方文档](https://flet.dev/docs/)
- [MusicLibrary](https://github.com/2061360308/MusicLibrary) — 音乐数据来源
- [Flet 打包指南](https://flet.dev/docs/publish/)

## ⚠️ 免责声明

本项目**仅用于 Flet 框架开发学习**，严禁用于任何商业用途。

- 本项目并非音乐平台的官方产品，与各音乐平台无关
- 所有音乐、歌词、封面等内容的版权均归各版权方所有
- 用户应遵守相关法律法规，下载后请在 24 小时内删除
- 任何商业使用、运营、盈利行为均被禁止
- 因使用本项目产生的任何法律问题，由使用者自行承担