g711-web-stream-player 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 AbelShine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,273 @@
+# g711-web-stream-player
+
+Clean and smooth G.711 audio playback for the Web.
+
+一个面向浏览器的轻量级 TypeScript G.711 流式音频库。它可以从 HTTP-FLV 流中提取 PCMA（A-law）或 PCMU（μ-law）音频，解码并通过 Web Audio API 播放，同时利用预缓冲、环形缓冲、插值升采样、噪声门和语音滤波改善实时音频的底噪与卡顿。
+
+核心库不依赖任何前端框架，并提供 Vue 2、Vue 3 和 React 适配入口。
+
+## 特性
+
+- G.711 A-law（PCMA）与 μ-law（PCMU）解码
+- HTTP-FLV 流式读取及音频 Tag 增量解析
+- 环形缓冲与可配置预缓冲，吸收网络抖动
+- Catmull-Rom 三次插值升采样，适配浏览器输出采样率
+- RMS 噪声门，压低无语音时的持续底噪
+- 高通滤波切除低频嗡声，高频搁架滤波补偿语音清晰度
+- 框架无关的 TypeScript API
+- Vue 2 / Vue 3 Composition API 适配
+- React Hook 适配
+- ESM、CommonJS 与完整类型声明
+
+## 安装
+
+当前可以直接从 GitHub 安装：
+
+```bash
+npm install github:AbelShine/g711-web-stream-player
+```
+
+发布到 npm 后可使用：
+
+```bash
+npm install g711-web-stream-player
+```
+
+只使用核心 API 时不需要安装框架依赖。使用框架适配入口时，再安装对应依赖：
+
+```bash
+# Vue 3 或 Vue 2.7
+npm install vue vue-demi
+
+# React
+npm install react
+```
+
+Vue 2.6 还需要 Composition API：
+
+```bash
+npm install vue@2.6 @vue/composition-api vue-demi
+```
+
+并在应用入口安装插件：
+
+```ts
+import Vue from 'vue'
+import VueCompositionAPI from '@vue/composition-api'
+
+Vue.use(VueCompositionAPI)
+```
+
+## 快速开始
+
+浏览器通常只允许在用户点击或触摸后启动音频。建议在播放按钮的事件处理函数中调用 `start()` 或 `resume()`。
+
+### 原生 JavaScript / TypeScript
+
+```ts
+import { FlvAudioStreamer } from 'g711-web-stream-player'
+
+const audio = new FlvAudioStreamer({
+  player: {
+    // 播放前积累 120ms 音频，用少量延迟换取更稳定的播放。
+    prebufferMs: 120,
+    // -42dBFS 左右关闭噪声门；设为 0 可关闭噪声门。
+    noiseGateThreshold: 0.008,
+    highpassHz: 180,
+    volume: 0.8,
+  },
+})
+
+document.querySelector('#play')?.addEventListener('click', () => {
+  // 实时流会持续读取，因此不要在点击处理器中 await。
+  void audio.start('https://example.com/live.flv', {
+    onCodecDetected(codec) {
+      console.log('检测到音频编码：', codec)
+    },
+    onError(error) {
+      console.error('音频流错误：', error)
+    },
+  })
+})
+
+document.querySelector('#stop')?.addEventListener('click', () => audio.stop())
+
+// 页面不再使用播放器时释放 AudioContext。
+window.addEventListener('beforeunload', () => audio.destroy())
+```
+
+### Vue 3
+
+```vue
+<script setup lang="ts">
+import { useG711Stream } from 'g711-web-stream-player/vue'
+
+const { isStreaming, codec, error, start, stop, setMuted, setVolume } = useG711Stream({
+  player: { prebufferMs: 120 },
+})
+
+function play() {
+  void start('https://example.com/live.flv')
+}
+</script>
+
+<template>
+  <button @click="play">播放</button>
+  <button @click="stop">停止</button>
+  <button @click="setMuted(true)">静音</button>
+  <input type="range" min="0" max="1" step="0.1" @input="setVolume(Number(($event.target as HTMLInputElement).value))" />
+  <span v-if="isStreaming">播放中：{{ codec || '检测中' }}</span>
+  <span v-if="error">{{ error.message }}</span>
+</template>
+```
+
+### Vue 2
+
+Vue 2.7 可以直接在 `setup()` 中使用；Vue 2.6 请先按照安装章节配置 `@vue/composition-api`。
+
+```ts
+import { defineComponent } from 'vue-demi'
+import { useG711Stream } from 'g711-web-stream-player/vue'
+
+export default defineComponent({
+  setup() {
+    const stream = useG711Stream({
+      player: { prebufferMs: 160 },
+    })
+
+    const play = () => {
+      void stream.start('https://example.com/live.flv')
+    }
+
+    return { ...stream, play }
+  },
+})
+```
+
+Vue 适配器会在组件卸载时自动销毁播放器和网络请求。
+
+### React
+
+```tsx
+import { useG711Stream } from 'g711-web-stream-player/react'
+
+export function AudioControls() {
+  const { isStreaming, codec, error, start, stop, setMuted } = useG711Stream({
+    player: { prebufferMs: 120 },
+  })
+
+  return (
+    <section>
+      <button onClick={() => void start('https://example.com/live.flv')}>播放</button>
+      <button onClick={stop}>停止</button>
+      <button onClick={() => setMuted(true)}>静音</button>
+      <p>{isStreaming ? `播放中：${codec ?? '检测中'}` : '已停止'}</p>
+      {error && <p role="alert">{error.message}</p>}
+    </section>
+  )
+}
+```
+
+React Hook 会在组件卸载时自动销毁播放器和网络请求。
+
+## 播放原始 G.711 数据包
+
+如果项目已经通过 WebSocket、WebRTC 数据通道或其他方式拿到了原始 G.711 包，可以绕过 FLV 解析器：
+
+```ts
+import { G711AudioPlayer } from 'g711-web-stream-player'
+
+const player = new G711AudioPlayer({ prebufferMs: 100 })
+
+playButton.addEventListener('click', () => {
+  player.init()
+})
+
+socket.addEventListener('message', (event) => {
+  player.pushChunk(new Uint8Array(event.data), 'pcma')
+})
+```
+
+仅需要解码时也可以直接调用：
+
+```ts
+import { decodeG711Chunk, decodeG711ToFloat32 } from 'g711-web-stream-player'
+
+const pcm16 = decodeG711Chunk(packet, 'pcmu')
+const webAudioSamples = decodeG711ToFloat32(packet, 'pcmu')
+```
+
+## 核心配置
+
+`G711AudioPlayer` 或 `FlvAudioStreamer` 的 `player` 字段支持以下常用选项：
+
+| 选项 | 默认值 | 说明 |
+| --- | ---: | --- |
+| `inputSampleRate` | `8000` | 输入 G.711 采样率 |
+| `prebufferMs` | `120` | 首次播放及欠载后的预缓冲时长；网络差时可调至 160–300ms |
+| `bufferDurationMs` | `4000` | 环形缓冲最大容量 |
+| `overflowDropMs` | `150` | 缓冲溢出时丢弃的旧音频时长 |
+| `processorBufferSize` | `2048` | Web Audio 处理块大小 |
+| `cubicInterpolation` | `true` | 是否使用三次插值升采样 |
+| `noiseGateThreshold` | `0.008` | RMS 噪声门阈值；`0` 表示关闭 |
+| `noiseGateFloor` | `0.18` | 噪声门关闭时保留的增益 |
+| `noiseGateRelease` | `0.35` | 噪声门关闭速度 |
+| `highpassHz` | `180` | 高通截止频率；`0` 表示关闭 |
+| `highshelfHz` | `2600` | 高频补偿起始频率；`0` 表示关闭 |
+| `highshelfGainDb` | `2` | 高频补偿增益 |
+| `volume` | `1` | 初始音量，范围 0–1 |
+| `muted` | `false` | 是否初始静音 |
+
+### 调优建议
+
+- 仍然偶发卡顿：优先增大 `prebufferMs`，代价是播放延迟增加。
+- 人声开头被截断：降低 `noiseGateThreshold` 或把它设为 `0`。
+- 环境低频声过重：适当提高 `highpassHz`，但过高会让人声变薄。
+- 音频延迟不断增大：减小 `bufferDurationMs` 或增大 `overflowDropMs`。
+
+## FLV 输入要求
+
+- FLV Audio Tag 的 `SoundFormat` 必须为 `7`（G.711 A-law）或 `8`（G.711 μ-law）。
+- HTTP-FLV 地址必须允许浏览器跨域访问（CORS）。
+- 如果接口需要 Cookie，请通过 `extractor.requestInit.credentials` 配置。
+- HTTPS 页面不能直接请求 HTTP 流，否则会被浏览器的混合内容策略阻止。
+
+带认证信息的示例：
+
+```ts
+const audio = new FlvAudioStreamer({
+  extractor: {
+    requestInit: {
+      credentials: 'include',
+      headers: { Authorization: 'Bearer ...' },
+    },
+  },
+})
+```
+
+请勿在公开代码、日志或 Issue 中提交真实令牌和内网流地址。
+
+## 开发
+
+```bash
+git clone https://github.com/AbelShine/g711-web-stream-player.git
+cd g711-web-stream-player
+npm install
+npm run check
+```
+
+构建产物位于 `dist/`：
+
+- `index`：框架无关核心 API
+- `vue`：Vue 2 / Vue 3 Composition API 适配器
+- `react`：React Hook 适配器
+
+## 浏览器兼容性
+
+需要浏览器支持 Fetch、ReadableStream 和 Web Audio API。移动端浏览器通常要求用户手势触发播放。
+
+当前播放器使用兼容性较好的 `ScriptProcessorNode`。它已被 Web Audio 标准标记为 deprecated，但在主流浏览器仍有广泛支持；后续版本计划提供 AudioWorklet 后端。
+
+## License
+
+[MIT](LICENSE)