@roitium/expo-orpheus 0.9.3 → 0.10.0

package/.commitlintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+};

package/.env

@@ -0,0 +1 @@
+GITHUB_TOKEN=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

package/.release-it.json

@@ -0,0 +1,19 @@
+{
+  "git": {
+    "commitMessage": "chore: release v${version}",
+    "tagName": "v${version}",
+    "requireCleanWorkingDir": true
+  },
+  "npm": {
+    "publish": true
+  },
+  "github": {
+    "release": true
+  },
+  "plugins": {
+    "@release-it/conventional-changelog": {
+      "preset": "angular",
+      "infile": "CHANGELOG.md"
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+
+
+# [0.10.0](https://github.com/bbplayer-app/orpheus/compare/v0.9.4...v0.10.0) (2026-01-27)
+
+
+### Features
+
+* 1 ([ef1f7ba](https://github.com/bbplayer-app/orpheus/commit/ef1f7ba5ad05d23f62b5c0d19b84639355b8280b))
+* 1 ([f386be4](https://github.com/bbplayer-app/orpheus/commit/f386be4fd7a0ac05bff6d31e31ec87094c7bdccf))
+* Add commitlint, husky hooks, and release-it, enhance the example application with new UI components and test data, and provide comprehensive API documentation. ([7b8aefd](https://github.com/bbplayer-app/orpheus/commit/7b8aefd94f0789a3c0686074e1c9f68bcae0b901))

package/README.md

@@ -4,38 +4,18 @@
 
 这是一个为 BBPlayer 项目构建的高性能定制音频播放库。旨在替代 `react-native-track-player`，以提供与 Android Media3 (ExoPlayer) 更紧密的集成，并针对 Bilibili 音频流逻辑提供了原生层支持。
 
-## 与 B 站集成
+## 功能特性
 
-通过 `Orpheus.setBilibiliCookie()` 设置 cookie，稍后会自动用于音频流请求。（不设置也行，只是无法获取高码率的音频）
+- **Bilibili 集成**: 自动处理 Bilibili 音频流，支持高码率（需 Cookie）。
+- **双层缓存**: 包含独立的下载缓存和边下边播 LRU 缓存。
+- **Android Media3**: 基于最新的 Media3 和 ExoPlayer 架构。
+- **桌面歌词**: 支持系统级桌面歌词悬浮窗。
+- **ExoPlayer 扩展**: 支持 `ffmpeg` 扩展（如需要）。
 
-Orpheus 通过特殊的 uri 识别来自 bilibili 的资源，格式为 `orpheus://bilibili?bvid=xxx&cid=111&quality=30280&dolby=0&hires=0`，若不提供 cid 则默认请求第一个分 p。quality 参考 b 站 api。
+## 文档
 
-## 缓存
+详细的 API 文档和使用说明请参阅 [Wiki](docs/Home.md) 或直接查看 `docs/` 目录。
 
-Orpheus 内部有两层缓存：
+## 声明
 
-1. 用户手动下载的缓存
-2. 边下边播：LRU 缓存，256mb
-
-## 下载系统
-
-Orpheus 集成了 Media3 的 DownloadManager，抛弃了原先 BBPlayer 中繁琐的下载实现。
-
-## 响度均衡
-
-默认启用，只对未缓存的 b 站音频生效
-
-## 桌面歌词
-
-相信聪明的你去看一下公开方法名就知道怎么使用了！
-（需要注意的是，在切歌时，会自动清空当前的歌词）
-
-## 注意事项
-
-该库一些修改比较随意，我怕后续我自己都忘了，所以在这里进行一下记录。
-
-1. `onTrackStarted` 事件在 v0.9.0 版本后不再存在。需要使用 `registerOrpheusHeadlessTask` 注册事件并自行判断事件是否为 `onTrackStarted`
-
-## 使用
-
-虽然该包是公开的，但仍然主要供 BBPlayer 内部使用。可能不会有完整的文档覆盖。我们欢迎你 fork 后自行修改使用。
+该库主要供 BBPlayer 内部使用，虽然开源，但可能不会处理外部的 Feature Request。

package/android/build.gradle

@@ -1,7 +1,12 @@
 apply plugin: 'com.android.library'
 
+import groovy.json.JsonSlurper
+
+def packageJsonFile = new File(rootProject.projectDir, '../package.json')
+def packageJson = new JsonSlurper().parseText(packageJsonFile.text)
+
 group = 'expo.modules.orpheus'
-version = '0.1.0'
+version = packageJson.version
 
 def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
 apply from: expoModulesCorePlugin
@@ -35,7 +40,7 @@ android {
     namespace "expo.modules.orpheus"
     defaultConfig {
         versionCode 1
-        versionName "0.1.0"
+        versionName packageJson.version
     }
     lintOptions {
         abortOnError false

package/android/src/main/java/expo/modules/orpheus/OrpheusMusicService.kt

@@ -173,6 +173,7 @@ class OrpheusMusicService : MediaLibraryService() {
                     .build(),
                 true
             )
+            .setHandleAudioBecomingNoisy(true)
             .build()
 
         floatingLyricsManager = FloatingLyricsManager(this, player)

package/docs/API-Events.md

@@ -0,0 +1,35 @@
+# 事件与后台任务
+
+## 事件监听 (Events)
+
+使用 `Orpheus.addListener(eventName, callback)` 进行监听。
+
+| 事件名                   | 参数                                   | 描述                                         |
+| :----------------------- | :------------------------------------- | :------------------------------------------- |
+| `onPlaybackStateChanged` | `{ state: PlaybackState }`             | 播放状态改变 (IDLE, BUFFERING, READY, ENDED) |
+| `onIsPlayingChanged`     | `{ status: boolean }`                  | 播放/暂停状态改变                            |
+| `onTrackFinished`        | `{ trackId, finalPosition, duration }` | 歌曲播放完成                                 |
+| `onPositionUpdate`       | `{ position, duration, buffered }`     | 进度更新 (约 500ms 一次)                     |
+| `onPlayerError`          | `{ code, message }`                    | 播放器报错                                   |
+| `onDownloadUpdated`      | `DownloadTask`                         | 下载进度更新                                 |
+| `onPlaybackSpeedChanged` | `{ speed: number }`                    | 倍速改变                                     |
+
+**注意**: `onTrackStarted` 事件在 v0.9.0+ 已移除，请使用 Headless Task。
+
+## 后台任务 (Headless Task)
+
+为了在 App 后台或被杀掉进程时仍能处理切歌等逻辑（如更新通知栏或以前的 `onTrackStarted` 逻辑），你需要注册 Headless Task。
+
+```typescript
+import { registerOrpheusHeadlessTask } from "@roitium/expo-orpheus";
+
+registerOrpheusHeadlessTask(async (event) => {
+  // 目前主要处理 TrackStarted 事件
+  if (event.eventName === "onTrackStarted") {
+    console.log("开始播放:", event.trackId);
+    console.log("原因:", event.reason); // 0: REPEAT, 1: AUTO, 2: SEEK, 3: PLAYLIST_CHANGED
+  }
+});
+```
+
+必须在 `index.js` 或应用启动的最早时期注册。

package/docs/API-Methods.md

@@ -0,0 +1,107 @@
+# API 方法
+
+## 播放控制 (Playback Control)
+
+- **`play(): Promise<void>`**
+  恢复播放。
+
+- **`pause(): Promise<void>`**
+  暂停播放。
+
+- **`skipToNext(): Promise<void>`**
+  跳至下一首。
+
+- **`skipToPrevious(): Promise<void>`**
+  跳至上一首。
+
+- **`skipTo(index: number): Promise<void>`**
+  跳至播放队列中的指定索引。
+
+- **`seekTo(seconds: number): Promise<void>`**
+  跳转到当前曲目的指定时间（单位：秒）。
+
+- **`setPlaybackSpeed(speed: number): Promise<void>`**
+  设置播放倍速 (如 1.0, 1.25, 2.0)。
+
+- **`getPlaybackSpeed(): Promise<number>`**
+  获取当前倍速。
+
+## 队列管理 (Queue Management)
+
+- **`addToEnd(tracks: Track[], startFromId?: string, clearQueue?: boolean): Promise<void>`**
+  将歌曲添加到队列末尾。
+  - `tracks`: 歌曲列表。
+  - `startFromId` (可选): 添加后由该 ID 开始播放。
+  - `clearQueue` (可选): 是否先清空队列。
+
+- **`playNext(track: Track): Promise<void>`**
+  插队播放（下一首）。
+
+- **`clear(): Promise<void>`**
+  清空队列。
+
+- **`removeTrack(index: number): Promise<void>`**
+  移除指定索引的歌曲。
+
+- **`getQueue(): Promise<Track[]>`**
+  获取完整播放队列。
+
+- **`getCurrentIndex(): Promise<number>`**
+  获取当前播放索引。
+
+- **`getCurrentTrack(): Promise<Track | null>`**
+  获取当前播放对象。
+
+- **`getIndexTrack(index: number): Promise<Track | null>`**
+  获取指定索引的对象。
+
+## 下载管理 (Downloads)
+
+Orpheus 使用 Media3 DownloadManager。
+
+- **`downloadTrack(track: Track): Promise<void>`**
+  下载单曲。
+
+- **`multiDownload(tracks: Track[]): Promise<void>`**
+  批量下载。
+
+- **`removeDownload(id: string): Promise<void>`**
+  移除下载。
+
+- **`removeAllDownloads(): Promise<void>`**
+  清空下载缓存。
+
+- **`getDownloads(): Promise<DownloadTask[]>`**
+  获取所有下载任务。
+
+- **`getDownloadStatusByIds(ids: string[]): Promise<Record<string, DownloadState>>`**
+  批量查询下载状态。
+
+- **`getUncompletedDownloadTasks(): Promise<DownloadTask[]>`**
+  获取未完成任务。
+
+- **`clearUncompletedDownloadTasks(): Promise<void>`**
+  清除未完成（失败/停止）的任务。
+
+## 杂项与配置 (Misc)
+
+- **`setSleepTimer(durationMs: number): Promise<void>`**
+  设置睡眠定时器（毫秒）。
+
+- **`getSleepTimerEndTime(): Promise<number | null>`**
+  获取定时器结束时间戳。
+
+- **`cancelSleepTimer(): Promise<void>`**
+  取消定时器。
+
+- **`setBilibiliCookie(cookie: string): void`**
+  设置 Bilibili Cookie。
+
+- **`showDesktopLyrics() / hideDesktopLyrics()`**
+  显示/隐藏桌面歌词。
+
+- **`checkOverlayPermission() / requestOverlayPermission()`**
+  权限检查与请求。
+
+- **`setDesktopLyrics(json: string)`**
+  更新歌词内容。

package/docs/API-Types.md

@@ -0,0 +1,89 @@
+# 数据类型 (Types)
+
+## Track
+
+核心音频对象结构。
+
+```typescript
+export interface Track {
+  /** 唯一标识符 */
+  id: string;
+
+  /**
+   * 音频流地址。
+   * 特殊协议: orpheus://bilibili?bvid=...
+   */
+  url: string;
+
+  /** 标题 */
+  title?: string;
+
+  /** 艺术家 */
+  artist?: string;
+
+  /** 封面图 URL */
+  artwork?: string;
+
+  /** 时长 (秒) */
+  duration?: number;
+
+  /**
+   * 响度标准化参数
+   * 用于 ReplayGain 或类似处理
+   */
+  loudness?: {
+    measured_i: number; // 测量的各向同性响度 (LUFS)
+    target_i: number; // 目标响度
+  };
+}
+```
+
+## PlaybackState
+
+播放器状态枚举。
+
+```typescript
+export enum PlaybackState {
+  IDLE = 1, // 空闲 / 无资源
+  BUFFERING = 2, // 缓冲中
+  READY = 3, // 准备就绪 / 可播放
+  ENDED = 4, // 播放结束
+}
+```
+
+## RepeatMode
+
+重复模式。
+
+```typescript
+export enum RepeatMode {
+  OFF = 0, // 不重复
+  TRACK = 1, // 单曲循环
+  QUEUE = 2, // 列表循环
+}
+```
+
+## DownloadTask & DownloadState
+
+下载任务详情。
+
+```typescript
+export enum DownloadState {
+  QUEUED = 0,
+  STOPPED = 1,
+  DOWNLOADING = 2,
+  COMPLETED = 3,
+  FAILED = 4,
+  REMOVING = 5,
+  RESTARTING = 7,
+}
+
+export interface DownloadTask {
+  id: string;
+  state: DownloadState;
+  percentDownloaded: number; // 0 - 100
+  bytesDownloaded: number;
+  contentLength: number;
+  track?: Track; // 关联的 Track 对象信息
+}
+```

package/docs/Home.md

@@ -0,0 +1,22 @@
+# 欢迎使用 Orpheus
+
+**BBPlayer 内部音频模块**
+
+Orpheus 是一个为 BBPlayer 构建的高性能音频播放库，基于 Android Media3 (ExoPlayer)。
+
+## 目录
+
+- [API 方法 (Methods)](API-Methods.md)
+- [数据类型 (Types)](API-Types.md)
+- [事件与后台任务 (Events)](API-Events.md)
+- [发版指南 (Releasing)](RELEASING.md)
+
+## 快速开始
+
+Orpheus 主要用于处理复杂的音频播放需求，特别是 Bilibili 音频流和本地缓存管理。
+
+### 核心特性
+
+- **Bilibili 支持**: 如果提供了 Bilibili Cookie，Orpheus 可以自动获取高音质流。
+- **缓存系统**: 内置 LRU 缓存（边下边播）和持久化下载管理。
+- **桌面歌词**: Android 系统级悬浮窗歌词支持。

package/docs/RELEASING.md

@@ -0,0 +1,34 @@
+# 发版指南 (Releasing)
+
+本项目使用 `release-it` 配合 Conventional Commits 进行自动化发版。
+
+## 准备工作
+
+1. 确保你的代码已提交并推送到远程分支。
+2. 确保你有 `npm` 发布权限 (需 `npm login`)。
+3. 建议配置 `GITHUB_TOKEN` 环境变量以支持自动创建 GitHub Release。
+
+## 发版流程
+
+在项目根目录运行：
+
+```bash
+npm run release
+```
+
+该命令会自动执行以下步骤：
+
+1. **版本升级**: 根据 commit message (feat/fix/breaking) 自动计算下一个版本号 (SemVer)。
+2. **Changelog**: 生成/更新 `CHANGELOG.md`。
+3. **Git**: 创建 git tag 并提交。
+4. **Publish**: 发布到 NPM。
+5. **GitHub**: 创建 GitHub Release (包含 Changelog)。
+
+## 提交规范
+
+请务必遵守 Conventional Commits 规范，否则 `commitlint` 会拦截提交，且无法生成正确的 Changelog。
+
+- `feat: ...` -> Minor 版本 (0.1.0 -> 0.2.0)
+- `fix: ...` -> Patch 版本 (0.1.0 -> 0.1.1)
+- `chore: ...` -> 不触发版本更新 (除非手动指定)
+- `BREAKING CHANGE: ...` -> Major 版本 (0.1.0 -> 1.0.0)

package/expo-module.config.json

@@ -1,6 +1,9 @@
 {
-  "platforms": ["android"],
+  "platforms": ["android", "ios"],
   "android": {
     "modules": ["expo.modules.orpheus.ExpoOrpheusModule"]
+  },
+  "ios": {
+    "modules": ["ExpoOrpheusModule"]
   }
 }

package/ios/BilibiliApi.swift

@@ -0,0 +1,246 @@
+import Foundation
+
+enum BilibiliError: Error {
+    case invalidUrl
+    case requestFailed
+    case decodingFailed
+    case navInfoMissing
+    case noData
+    case apiError(code: Int, message: String)
+}
+
+struct BilibiliNavResponse: Codable {
+    let code: Int
+    let data: NavData?
+    
+    struct NavData: Codable {
+        let wbi_img: WbiImg?
+        let isLogin: Bool?
+    }
+    
+    struct WbiImg: Codable {
+        let img_url: String
+        let sub_url: String
+    }
+}
+
+struct BilibiliPlayUrlResponse: Codable {
+    let code: Int
+    let message: String?
+    let data: PlayUrlData?
+    
+    struct PlayUrlData: Codable {
+        let durl: [Durl]?
+        let dash: Dash?
+    }
+    
+    struct Durl: Codable {
+        let url: String
+        let backup_url: [String]?
+    }
+    
+    struct Dash: Codable {
+        let audio: [DashAudio]?
+    }
+    
+    struct DashAudio: Codable {
+        let id: Int
+        let baseUrl: String
+        let backupUrl: [String]?
+    }
+}
+
+// Response for PageList
+struct BilibiliPageListResponse: Codable {
+    let code: Int
+    let message: String?
+    let data: [BilibiliPageListItem]?
+}
+
+struct BilibiliPageListItem: Codable {
+    let cid: Int
+    let page: Int
+    let part: String
+}
+
+class BilibiliApi {
+    static let shared = BilibiliApi()
+    
+    private let session = URLSession.shared
+    private var cookie: String?
+    
+    // Wbi keys cache
+    private var imgKey: String?
+    private var subKey: String?
+    private var wbiKeysUpdatedAt: Date?
+    
+    func setCookie(_ cookie: String) {
+        self.cookie = cookie
+    }
+    
+    func getPageList(bvid: String, completion: @escaping (Result<Int, Error>) -> Void) {
+         var components = URLComponents(string: "https://api.bilibili.com/x/player/pagelist")!
+         components.queryItems = [URLQueryItem(name: "bvid", value: bvid)]
+         
+         var request = URLRequest(url: components.url!)
+         request.httpMethod = "GET"
+         if let cookie = cookie {
+             request.setValue(cookie, forHTTPHeaderField: "Cookie")
+         }
+         
+         print("[BilibiliApi] getPageList: Requesting \(request.url?.absoluteString ?? "nil")")
+         
+         session.dataTask(with: request) { data, response, error in
+             if let error = error {
+                 completion(.failure(error))
+                 return
+             }
+             
+             guard let data = data else {
+                 completion(.failure(BilibiliError.noData))
+                 return
+             }
+             
+             do {
+                 let apiResponse = try JSONDecoder().decode(BilibiliPageListResponse.self, from: data)
+                 if apiResponse.code != 0 {
+                     print("[BilibiliApi] getPageList error: \(apiResponse.code) \(apiResponse.message ?? "")")
+                     completion(.failure(BilibiliError.apiError(code: apiResponse.code, message: apiResponse.message ?? "Unknown error")))
+                     return
+                 }
+                 
+                 if let firstPage = apiResponse.data?.first {
+                     completion(.success(firstPage.cid))
+                 } else {
+                     completion(.failure(BilibiliError.decodingFailed)) // Or specific "Empty List" error
+                 }
+             } catch {
+                 print("[BilibiliApi] getPageList decode failed: \(error)")
+                 completion(.failure(error))
+             }
+         }.resume()
+    }
+    
+    func refreshNavInfo(completion: @escaping (Result<Void, Error>) -> Void) {
+        let urlStr = "https://api.bilibili.com/x/web-interface/nav"
+        guard let url = URL(string: urlStr) else {
+            completion(.failure(BilibiliError.invalidUrl))
+            return
+        }
+        
+        var request = URLRequest(url: url)
+        if let cookie = cookie {
+            request.setValue(cookie, forHTTPHeaderField: "Cookie")
+        }
+        request.setValue("https://www.bilibili.com", forHTTPHeaderField: "Referer")
+        request.setValue("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36", forHTTPHeaderField: "User-Agent")
+        
+        session.dataTask(with: request) { [weak self] data, response, error in
+            if let error = error {
+                completion(.failure(error))
+                return
+            }
+            
+            guard let data = data else {
+                completion(.failure(BilibiliError.requestFailed))
+                return
+            }
+            
+            do {
+                let navResponse = try JSONDecoder().decode(BilibiliNavResponse.self, from: data)
+                if let wbiImg = navResponse.data?.wbi_img {
+                    self?.imgKey = WbiUtil.extractKey(url: wbiImg.img_url)
+                    self?.subKey = WbiUtil.extractKey(url: wbiImg.sub_url)
+                    completion(.success(()))
+                } else {
+                    completion(.failure(BilibiliError.navInfoMissing))
+                }
+            } catch {
+                completion(.failure(error))
+            }
+        }.resume()
+    }
+    
+    func getPlayUrl(bvid: String, cid: String, completion: @escaping (Result<String, Error>) -> Void) {
+        guard let imgKey = imgKey, let subKey = subKey else {
+            // Refresh nav info first
+            refreshNavInfo { result in
+                switch result {
+                case .success:
+                    self.getPlayUrl(bvid: bvid, cid: cid, completion: completion)
+                case .failure(let error):
+                    completion(.failure(error))
+                }
+            }
+            return
+        }
+        
+        let params: [String: Any] = [
+            "bvid": bvid,
+            "cid": cid,
+            "qn": 80, // 1080P
+            // fnval=1 requests MP4/FLV durl list which is better for AVPlayer
+            "fnval": 1, 
+            "fnver": 0,
+            "fourk": 1,
+            "platform": "html5" // Explicitly request html5 compatible (mp4)
+        ]
+        
+        let signedParams = WbiUtil.sign(params: params, imgKey: imgKey, subKey: subKey)
+        
+        var components = URLComponents(string: "https://api.bilibili.com/x/player/wbi/playurl")!
+        components.queryItems = signedParams.map { URLQueryItem(name: $0.key, value: $0.value) }
+        
+        print("[BilibiliApi] getPlayUrl: Requesting \(components.url?.absoluteString ?? "nil")")
+        
+        var request = URLRequest(url: components.url!)
+        if let cookie = cookie {
+            request.setValue(cookie, forHTTPHeaderField: "Cookie")
+        }
+        request.setValue("https://www.bilibili.com", forHTTPHeaderField: "Referer")
+        request.setValue("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36", forHTTPHeaderField: "User-Agent")
+        
+        session.dataTask(with: request) { data, response, error in
+            if let error = error {
+                print("[BilibiliApi] Request failed: \(error)")
+                completion(.failure(error))
+                return
+            }
+            
+            guard let data = data else {
+                completion(.failure(BilibiliError.requestFailed))
+                return
+            }
+            
+            // Debug print response
+            if let str = String(data: data, encoding: .utf8) {
+                print("[BilibiliApi] Response: \(str)")
+            }
+            
+            do {
+                let playUrlResponse = try JSONDecoder().decode(BilibiliPlayUrlResponse.self, from: data)
+                
+                if playUrlResponse.code != 0 {
+                     print("[BilibiliApi] API returned error code: \(playUrlResponse.code), message: \(playUrlResponse.message ?? "nil")")
+                     completion(.failure(BilibiliError.requestFailed)) // Create specific error?
+                     return
+                }
+                
+                // Prioritize Dash Audio, then Durl
+                if let audioUrl = playUrlResponse.data?.dash?.audio?.first?.baseUrl {
+                    print("[BilibiliApi] Found DASH audio URL")
+                    completion(.success(audioUrl))
+                } else if let mp4Url = playUrlResponse.data?.durl?.first?.url {
+                    print("[BilibiliApi] Found MP4/DURL URL")
+                    completion(.success(mp4Url))
+                } else {
+                    print("[BilibiliApi] No playable URL found in response")
+                    completion(.failure(BilibiliError.decodingFailed)) // Or specific "not found"
+                }
+            } catch {
+                print("[BilibiliApi] Decode failed: \(error)")
+                completion(.failure(error))
+            }
+        }.resume()
+    }
+}