xgplayer-mp3 0.0.0-stage → 3.0.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,201 @@
1
- # Temporary Holding Version
1
+ # xgplayer-mp3
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ English | [简体中文](./README.zh-CN.md)
4
+
5
+ `xgplayer-mp3` is an xgplayer streaming plugin for standalone MP3 files. It
6
+ loads data on demand with HTTP Range requests and provides MSE-based seeking
7
+ for CBR and indexed VBR files. When the runtime or input is unsupported, the
8
+ plugin falls back to native `<audio>` playback by default.
9
+
10
+ ## Installation
11
+
12
+ ```bash
13
+ npm install xgplayer xgplayer-mp3
14
+ ```
15
+
16
+ Or:
17
+
18
+ ```bash
19
+ yarn add xgplayer xgplayer-mp3
20
+ ```
21
+
22
+ ## Basic usage
23
+
24
+ ```html
25
+ <div id="player"></div>
26
+ ```
27
+
28
+ ```js
29
+ import Player from 'xgplayer'
30
+ import MP3Plugin from 'xgplayer-mp3'
31
+ import 'xgplayer/dist/index.min.css'
32
+
33
+ const player = new Player({
34
+ id: 'player',
35
+ url: 'https://example.com/audio.mp3',
36
+ mediaType: 'audio',
37
+ plugins: [MP3Plugin]
38
+ })
39
+ ```
40
+
41
+ When `mp3` options are omitted, the plugin uses its default buffering,
42
+ segmentation, and retry settings.
43
+
44
+ ## HTTP Range and CORS
45
+
46
+ The server should support HTTP Range requests for on-demand loading and
47
+ seeking. A cross-origin `206` response should include headers similar to:
48
+
49
+ ```http
50
+ HTTP/1.1 206 Partial Content
51
+ Content-Type: audio/mpeg
52
+ Accept-Ranges: bytes
53
+ Content-Range: bytes 0-131071/2892276
54
+ Access-Control-Allow-Origin: *
55
+ Access-Control-Expose-Headers: Content-Range, Content-Length, Accept-Ranges
56
+ ```
57
+
58
+ If the server ignores the Range header and returns the complete file with
59
+ `200`, playback still works, but the entire file is downloaded and retained in
60
+ memory.
61
+
62
+ For a `206` response, JavaScript must be able to read a `Content-Range` header
63
+ that contains the complete file size. Otherwise, the plugin falls back to
64
+ native playback.
65
+
66
+ ## Configuration
67
+
68
+ Pass plugin options through the player's `mp3` field:
69
+
70
+ ```js
71
+ const player = new Player({
72
+ // ...
73
+ plugins: [MP3Plugin],
74
+ mp3: {
75
+ maxBufferLength: 60,
76
+ bufferBehind: 20,
77
+ segmentDuration: 15,
78
+ timeout: 10000
79
+ }
80
+ })
81
+ ```
82
+
83
+ Common options:
84
+
85
+ | Option | Default | Description |
86
+ | --- | ---: | --- |
87
+ | `maxBufferLength` | `40` | Target forward buffer while playing, in seconds |
88
+ | `minBufferLength` | `5` | Target forward buffer while paused, in seconds |
89
+ | `bufferBehind` | `30` | Buffered history retained behind the current time, in seconds |
90
+ | `segmentDuration` | `10` | Target audio duration of each Range segment, in seconds |
91
+ | `retry` | `3` | Number of network retries |
92
+ | `retryDelay` | `1000` | Delay between retries, in milliseconds |
93
+ | `timeout` | `5000` | Timeout for one network request, in milliseconds |
94
+ | `reqOptions` | `null` | Request options such as method, headers, and credentials |
95
+ | `closeDowngrade` | `false` | Disable fallback to native playback after a fatal plugin error |
96
+
97
+ Advanced options:
98
+
99
+ | Option | Default | Description |
100
+ | --- | ---: | --- |
101
+ | `tickInterval` | `500` | Buffer scheduling interval, in milliseconds |
102
+ | `probeSize` | `131072` | Number of bytes used for the initial format probe |
103
+ | `maxProbeSize` | `1048576` | Maximum probe size when skipping a large ID3 tag |
104
+ | `syncSearchSize` | `4096` | Number of bytes searched backward for MP3 frame sync during seek |
105
+ | `preferMMS` | `false` | Prefer `ManagedMediaSource` when available |
106
+ | `mseAttachMode` | `'auto'` | MediaSource attachment mode: `auto`, `src`, or `source-element` |
107
+
108
+ `retryCount` is supported as an alias for `retry`.
109
+
110
+ ## Supported inputs
111
+
112
+ `xgplayer-mp3` supports MPEG Audio Layer III only. Layer I and Layer II are
113
+ outside its supported scope.
114
+
115
+ | Capability | Status | Notes |
116
+ | --- | --- | --- |
117
+ | Standalone `.mp3` URL | Supported | HTTP(S), Blob URL, or a request that returns the complete file |
118
+ | MPEG-1 Audio Layer III | Supported | Common music MP3, 1152 samples per frame |
119
+ | MPEG-2 Audio Layer III | Supported | Low-sample-rate MP3, 576 samples per frame |
120
+ | MPEG-2.5 Audio Layer III | Supported | Widely supported unofficial extension, 576 samples per frame |
121
+ | CBR | Supported | Initial duration is estimated from file size and corrected after a complete linear scan |
122
+ | Xing / Info | Supported | Xing VBR requires a TOC; Info CBR uses frame and byte counts |
123
+ | VBRI VBR | Supported | Uses the VBRI table for seek mapping |
124
+ | VBR without Xing/Info/VBRI | Native fallback | Accurate Range seeking is not guaranteed without a complete scan |
125
+ | Free-format MP3 | Native fallback | The frame header has no standard indexed bitrate |
126
+ | ID3v1 / ID3v2 | Supported | Tags may appear before, after, or between audio frames |
127
+ | DRM / EME | Unsupported | Only clear MP3 files are handled |
128
+
129
+ AAC and ADTS are not MP3 and are not handled by this plugin. The plugin also
130
+ does not include a software decoder; decoding depends on the browser's
131
+ `audio/mpeg` support.
132
+
133
+ ## Compatibility and fallback
134
+
135
+ Use the following check when runtime capability detection is required:
136
+
137
+ ```js
138
+ if (MP3Plugin.isSupported()) {
139
+ // audio/mpeg SourceBuffer is supported
140
+ }
141
+ ```
142
+
143
+ Manual detection is usually unnecessary. The plugin restores the original URL
144
+ and playback state, then delegates to native `<audio>` playback when:
145
+
146
+ - The runtime does not support `audio/mpeg` MSE.
147
+ - The file is unsupported or has no reliable seek mapping.
148
+ - A fatal error occurs during MSE initialization, loading, or appending.
149
+
150
+ Set `closeDowngrade: true` to disable native fallback and emit a terminal player
151
+ error instead.
152
+
153
+ ## MP3 format
154
+
155
+ MP3 is short for MPEG Audio Layer III. It is neither MPEG-3 nor a multitrack
156
+ container such as MP4:
157
+
158
+ ```text
159
+ [optional ID3v2]
160
+ [MP3 Frame 1]
161
+ [MP3 Frame 2]
162
+ ...
163
+ [optional ID3v1]
164
+ ```
165
+
166
+ MPEG Audio Version and Layer are independent dimensions:
167
+
168
+ | MPEG Audio Version | Sample rates | Layer III samples per frame | Typical use |
169
+ | --- | --- | ---: | --- |
170
+ | MPEG-1 | 32 / 44.1 / 48 kHz | 1152 | Music and high-quality audio |
171
+ | MPEG-2 | 16 / 22.05 / 24 kHz | 576 | Speech and low-bandwidth audio |
172
+ | MPEG-2.5 | 8 / 11.025 / 12 kHz | 576 | Very low-bandwidth speech |
173
+
174
+ Version is a field in the MPEG Audio frame header and is unrelated to standard
175
+ families such as MPEG-4.
176
+
177
+ ## How it works
178
+
179
+ ![xgplayer-mp3 playback pipeline](./docs/mp3-mse-flow.svg)
180
+
181
+ The plugin probes ID3 data, MP3 frames, and Xing/Info/VBRI indexes. It then maps
182
+ playback time to byte positions and loads frame-aligned data through HTTP Range
183
+ requests.
184
+
185
+ `xgplayer-mp3` follows the
186
+ [MPEG Audio MSE Byte Stream Format](https://www.w3.org/TR/mse-byte-stream-format-mpeg-audio/).
187
+ It appends frame-aligned MP3 data directly to an `audio/mpeg` SourceBuffer
188
+ without remuxing it to MP4. As required by the specification, `audio/mpeg` is
189
+ used without a `codecs` parameter.
190
+
191
+ ## Error identifiers
192
+
193
+ Fatal errors are reported through the `playCatch` event:
194
+
195
+ | `vtype` | Stage |
196
+ | --- | --- |
197
+ | `MP3_1` | Before the first data append completes |
198
+ | `MP3_2` | After the first data append completes |
199
+
200
+ With the default configuration, the plugin proceeds with native playback
201
+ fallback after emitting the event.
@@ -0,0 +1,189 @@
1
+ # xgplayer-mp3
2
+
3
+ [English](./README.md) | 简体中文
4
+
5
+ `xgplayer-mp3` 是面向独立 MP3 文件的 xgplayer 流式播放插件。它通过 HTTP
6
+ Range 按需加载,并为 CBR 和带索引的 VBR 文件提供基于 MSE 的 seek 能力。
7
+ 当运行环境或文件不满足要求时,默认交由浏览器原生 `<audio>` 播放。
8
+
9
+ ## 安装
10
+
11
+ ```bash
12
+ npm install xgplayer xgplayer-mp3
13
+ ```
14
+
15
+ 或者:
16
+
17
+ ```bash
18
+ yarn add xgplayer xgplayer-mp3
19
+ ```
20
+
21
+ ## 基础用法
22
+
23
+ ```html
24
+ <div id="player"></div>
25
+ ```
26
+
27
+ ```js
28
+ import Player from 'xgplayer'
29
+ import MP3Plugin from 'xgplayer-mp3'
30
+ import 'xgplayer/dist/index.min.css'
31
+
32
+ const player = new Player({
33
+ id: 'player',
34
+ url: 'https://example.com/audio.mp3',
35
+ mediaType: 'audio',
36
+ plugins: [MP3Plugin]
37
+ })
38
+ ```
39
+
40
+ 未传入 `mp3` 配置时,插件使用默认的 buffer、分段和重试策略。
41
+
42
+ ## HTTP 和 CORS 要求
43
+
44
+ 为实现按需加载和 seek,建议资源服务器支持 HTTP Range。跨域资源的 `206`
45
+ 响应示例:
46
+
47
+ ```http
48
+ HTTP/1.1 206 Partial Content
49
+ Content-Type: audio/mpeg
50
+ Accept-Ranges: bytes
51
+ Content-Range: bytes 0-131071/2892276
52
+ Access-Control-Allow-Origin: *
53
+ Access-Control-Expose-Headers: Content-Range, Content-Length, Accept-Ranges
54
+ ```
55
+
56
+ 如果服务器忽略 Range 并返回 `200` 完整文件,插件仍可播放,但会下载并在内存中
57
+ 保留完整文件。
58
+
59
+ 如果服务器返回 `206`,JavaScript 必须能够读取包含完整文件大小的
60
+ `Content-Range`,否则插件会降级到原生播放。
61
+
62
+ ## 配置
63
+
64
+ 通过播放器的 `mp3` 字段传入插件配置:
65
+
66
+ ```js
67
+ const player = new Player({
68
+ // ...
69
+ plugins: [MP3Plugin],
70
+ mp3: {
71
+ maxBufferLength: 60,
72
+ bufferBehind: 20,
73
+ segmentDuration: 15,
74
+ timeout: 10000
75
+ }
76
+ })
77
+ ```
78
+
79
+ 常用配置:
80
+
81
+ | 配置 | 默认值 | 说明 |
82
+ | --- | ---: | --- |
83
+ | `maxBufferLength` | `40` | 播放时向前预加载的目标时长,单位秒 |
84
+ | `minBufferLength` | `5` | 暂停时向前预加载的目标时长,单位秒 |
85
+ | `bufferBehind` | `30` | 当前时间之前保留的历史 buffer,单位秒 |
86
+ | `segmentDuration` | `10` | 每个 Range 分段期望覆盖的音频时长,单位秒 |
87
+ | `retry` | `3` | 网络请求重试次数 |
88
+ | `retryDelay` | `1000` | 网络请求重试间隔,单位毫秒 |
89
+ | `timeout` | `5000` | 单次网络请求超时,单位毫秒 |
90
+ | `reqOptions` | `null` | 请求的 method、headers、credentials 等选项 |
91
+ | `closeDowngrade` | `false` | 是否关闭出错时的原生播放降级 |
92
+
93
+ 高级配置:
94
+
95
+ | 配置 | 默认值 | 说明 |
96
+ | --- | ---: | --- |
97
+ | `tickInterval` | `500` | buffer 调度周期,单位毫秒 |
98
+ | `probeSize` | `131072` | 首次格式探测字节数 |
99
+ | `maxProbeSize` | `1048576` | 跳过大 ID3 标签时允许扩展的最大探测字节数 |
100
+ | `syncSearchSize` | `4096` | seek 时向前搜索 MP3 帧同步字的字节数 |
101
+ | `preferMMS` | `false` | 优先选择 ManagedMediaSource |
102
+ | `mseAttachMode` | `'auto'` | MediaSource 绑定方式:`auto`、`src`、`source-element` |
103
+
104
+ 同时兼容 `retryCount`,其值会映射到 `retry`。
105
+
106
+ ## 支持范围
107
+
108
+ `xgplayer-mp3` 仅支持 MPEG Audio Layer III;Layer I 和 Layer II 不在支持范围内。
109
+
110
+ | 能力 | 状态 | 说明 |
111
+ | --- | --- | --- |
112
+ | 独立 `.mp3` URL | 支持 | HTTP(S)、Blob URL 或返回完整文件的普通请求 |
113
+ | MPEG-1 Audio Layer III | 支持 | 常见音乐 MP3,1152 samples/frame |
114
+ | MPEG-2 Audio Layer III | 支持 | 低采样率 MP3,576 samples/frame |
115
+ | MPEG-2.5 Audio Layer III | 支持 | 广泛兼容的非正式扩展,576 samples/frame |
116
+ | CBR | 支持 | 初始时长按文件字节数估算,顺序下载完成后按实际帧修正 |
117
+ | Xing / Info | 支持 | Xing VBR 需要 TOC;Info CBR 使用 frame/byte count |
118
+ | VBRI VBR | 支持 | 使用 VBRI 表建立 seek 映射 |
119
+ | 无 Xing/Info/VBRI 的 VBR | 原生降级 | 不承诺未经完整扫描的精确 Range seek |
120
+ | Free-format MP3 | 原生降级 | 帧头没有可直接查询的标准码率索引 |
121
+ | ID3v1 / ID3v2 | 支持 | 可位于音频帧之前、之后或帧与帧之间 |
122
+ | DRM / EME | 不支持 | 当前仅处理明文 MP3 |
123
+
124
+ AAC / ADTS 不属于 MP3,本插件不处理这些格式。本插件也不提供软件解码,最终解码
125
+ 能力取决于浏览器对 `audio/mpeg` 的支持。
126
+
127
+ ## 兼容性与降级
128
+
129
+ 可以在运行时检测当前环境是否支持 MP3 MSE:
130
+
131
+ ```js
132
+ if (MP3Plugin.isSupported()) {
133
+ // 支持 audio/mpeg SourceBuffer
134
+ }
135
+ ```
136
+
137
+ 通常不需要在初始化前手动检测。出现以下情况时,插件默认恢复原始 URL 和播放状态,
138
+ 并交由浏览器原生 `<audio>` 继续处理:
139
+
140
+ - 当前环境不支持 `audio/mpeg` MSE。
141
+ - 文件不属于支持范围,或者无法建立可靠的 seek 映射。
142
+ - MSE 初始化、加载或追加数据时发生致命错误。
143
+
144
+ 设置 `closeDowngrade: true` 后,插件不会切换到原生播放,而是向播放器发出终止错误。
145
+
146
+ ## MP3 格式说明
147
+
148
+ MP3 是 MPEG Audio Layer III 的简称,不是 MPEG-3,也不是类似 MP4 的多轨容器:
149
+
150
+ ```text
151
+ [ID3v2,可选]
152
+ [MP3 Frame 1]
153
+ [MP3 Frame 2]
154
+ ...
155
+ [ID3v1,可选]
156
+ ```
157
+
158
+ MPEG Audio Version 与 Layer 是两个独立维度:
159
+
160
+ | MPEG Audio Version | 采样率 | Layer III 每帧采样数 | 常见定位 |
161
+ | --- | --- | ---: | --- |
162
+ | MPEG-1 | 32 / 44.1 / 48 kHz | 1152 | 音乐、高质量音频 |
163
+ | MPEG-2 | 16 / 22.05 / 24 kHz | 576 | 语音、低带宽音频 |
164
+ | MPEG-2.5 | 8 / 11.025 / 12 kHz | 576 | 超低带宽语音 |
165
+
166
+ 这里的 Version 是 MPEG Audio 帧头字段,与 MPEG-4 等标准家族的版本号无关。
167
+
168
+ ## 工作原理
169
+
170
+ ![xgplayer-mp3 playback pipeline](./docs/mp3-mse-flow.svg)
171
+
172
+ 插件首先探测 ID3、MP3 帧和 Xing/Info/VBRI 索引,再将播放时间映射到文件字节
173
+ 位置,通过 HTTP Range 加载帧对齐的数据。
174
+
175
+ `xgplayer-mp3` 遵循
176
+ [MPEG Audio MSE Byte Stream Format](https://www.w3.org/TR/mse-byte-stream-format-mpeg-audio/),
177
+ 将帧对齐的 MP3 数据直接追加到 `audio/mpeg` SourceBuffer,无需转封装为 MP4。
178
+ 按照该规范,`audio/mpeg` 不附加 `codecs` 参数。
179
+
180
+ ## 错误标识
181
+
182
+ 致命错误会通过 `playCatch` 事件对外通知:
183
+
184
+ | `vtype` | 阶段 |
185
+ | --- | --- |
186
+ | `MP3_1` | 首次数据追加完成前 |
187
+ | `MP3_2` | 首次数据追加完成后 |
188
+
189
+ 默认配置下,事件发出后插件会继续执行原生播放降级。