# bplayer

**Repository Path**: deepplayer/bplayer

## Basic Information

- **Project Name**: bplayer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# bplayer

仿 B 站风格的 HTML5 弹幕播放器 SDK，API 使用风格参考 [DPlayer](https://github.com/DIYgod/DPlayer)，弹幕协议与原项目保持一致（`code:23 + danmuku` 数组）。核心播放器完全独立，**后端可选**——不接后端也能单独使用（播放、控制条、记忆回放、自动下一集照常工作）。

## 组成

```
packages/
├── bplayer          # 播放器 SDK（Vite library 构建，ESM + UMD，TS 编写，原版 yzmplayer UI）
├── bplayer-backend  # 可选 Node 后端（Fastify + node:sqlite）：弹幕收发/搜索/举报/管理 + /bplayer/config
└── admin            # 可选 Vue 3 后台管理（登录 / 配置 / 弹幕管理）
demo/                # 演示页（有后端 / 无后端两种模式）
```

## 快速开始

### SDK

```bash
pnpm install
pnpm --filter bplayer build
```

```ts
import BPlayer from 'bplayer'
// 样式已内置（Shadow DOM 自包含），无需再引入 css

const bp = new BPlayer({
  container: '#player',
  theme: '#17CDB5',
  video: {
    url: 'https://example.com/video.mp4',
    pic: 'https://example.com/poster.jpg',
    type: 'auto', // auto | mp4 | hls | flv
  },
  danmaku: {
    id: 'video-001',   // 弹幕池 id
    api: '/dmku/',      // 后端地址；留空 = 无后端模式
    user: '游客',
  },
  server: {
    config: '/bplayer/config', // 可选：从后端拉取配置
    online: '/api/online',     // 可选：在线人数接口
  },
})

bp.play()
bp.seek(120)
bp.danmaku.send({ text: 'hello', color: '#fff', type: 'right', size: '25' })
bp.on('ended', () => console.log('ended'))

// 拉取后端配置（广告/主题/屏蔽词等），初始化传入的配置优先
await bp.fetchConfig()
// 或静态方法，只拉取不应用
const cfg = await BPlayer.fetchConfig('/bplayer/config')
```

### 后端

```bash
pnpm --filter bplayer-backend dev   # 开发模式（tsx watch）
pnpm --filter bplayer-backend build
pnpm --filter bplayer-backend start
```

默认监听 `0.0.0.0:3000`，首次启动在 `packages/bplayer-backend/data/` 生成 `config.json` 和 SQLite 数据库。默认后台账号 `admin / 123456`。

### 后台管理

```bash
pnpm --filter @bplayer/admin dev    # 开发（5173，代理到 3000）
pnpm --filter @bplayer/admin build
```

构建产物位于 `packages/admin/dist`，后端启动后自动托管在 `/admin/`。

## 配置项（Options）

所有配置在 `new BPlayer(options)` 初始化时传入，均为可选（除 `container` 与 `video`）。初始化时你显式传入的配置项优先级高于后端 `fetchConfig` 拉取到的配置，后端不会覆盖自定义值。

### 顶层选项 BPlayerOptions

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `container` | `string \| HTMLElement` | 必填 | 播放器挂载容器（CSS 选择器或元素），需有宽高 |
| `video` | `VideoOptions` | 必填 | 视频配置，见下方 |
| `autoplay` | `boolean` | `false` | 自动播放（浏览器可能拦截，会 notice 提示） |
| `theme` | `string` | `'#17CDB5'` | 主题色（进度条、弹幕边框等） |
| `logo` | `string` | `''` | 左上角 LOGO 文字 |
| `loop` | `boolean` | `false` | 洗脑循环播放 |
| `live` | `boolean` | `false` | 直播模式（隐藏进度条/倍速/循环等控件） |
| `volume` | `number` | `0.7` | 初始音量 0~1 |
| `hotkey` | `boolean` | `true` | 键盘快捷键（空格/k 播放暂停、左右 5s、f 全屏） |
| `screenshot` | `boolean` | `false` | 显示截图按钮 |
| `playbackSpeed` | `number[]` | `[0.5, 0.75, 1, 1.25, 1.5, 2]` | 可选倍速列表 |
| `danmaku` | `DanmakuOptions` | `{}` | 弹幕配置，见下方。**不配置该项则隐藏全部弹幕控件** |
| `subtitle` | `SubtitleOptions` | — | 字幕配置，见下方 |
| `ads` | `AdsOptions` | 见下方 | 广告配置（视频/图片/暂停广告） |
| `trysee` | `number` | `0` | 试看时长（分钟），超过后弹窗引导登录 |
| `loginUrl` | `string` | `''` | 试看弹窗"登录"按钮跳转地址 |
| `registerUrl` | `string` | `''` | 试看弹窗"注册"按钮跳转地址 |
| `blogUrl` | `string` | `'https://qkongtao.cn/'` | 右键菜单"站长博客"链接 |
| `next` | `string` | `''` | 下一集地址（显示下一集按钮，播放结束/片尾自动跳转） |
| `memory` | `boolean` | `true` | 记忆播放进度（cookie，下次打开提示续播） |
| `contextmenu` | `ContextMenuItem[]` | `[]` | 自定义右键菜单项（追加在默认项之后） |
| `apiBackend` | `ApiBackend` | 内置实现 | 自定义弹幕请求实现（send/read/report） |
| `waittime` | `number` | `5` | 续播提示等待秒数（对齐后端配置） |
| `sendtime` | `number` | `1` | 弹幕发送间隔秒数（对齐后端配置） |
| `dmrule` | `string` | `''` | 弹幕礼仪链接（弹幕框右侧） |
| `usernum` | `string` | `''` | 初始在线人数文案 |
| `danmuon` | `boolean \| 'on' \| 'off'` | — | 弹幕总开关。显式传入时优先于后端；未传时从后端 `danmuon` 读取 |
| `blockWords` | `string[]` | `[]` | 屏蔽关键词（与 `danmaku.blockWords` 合并） |
| `onlineApi` | `string` | — | （旧）在线人数接口，推荐改用 `server.online` |
| `config` | `{ api?: string }` | — | （旧）后端配置接口，推荐改用 `server.config` |
| `server` | `{ config?: string; online?: string; danmaku?: string }` | — | 统一的后端配置入口：需要从后端读取的地址都放这里 |

### video: VideoOptions

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | 必填 | 视频地址 |
| `pic` | `string` | — | 封面图 |
| `title` | `string` | `url` | 视频标题（左上角显示） |
| `type` | `'auto' \| 'mp4' \| 'hls' \| 'flv'` | `'auto'` | 自动按 URL 后缀识别，也可强制指定 |
| `quality` | `QualityItem[]` | — | 清晰度列表 `{ name, url, type? }`，配置后显示切换按钮 |
| `defaultQuality` | `number` | `0` | 默认清晰度下标 |
| `thumbnails` | `string` | — | 缩略图预览（进度条 hover 显示） |

### danmaku: DanmakuOptions

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `id` | `string` | — | 弹幕池 ID |
| `api` | `string` | — | 弹幕后端地址（如 `/dmku/`）；**留空 = 无后端模式**，不发起请求，播放/发送时提示未配置 |
| `av` | `string` | — | B 站 AV 号，追加官方弹幕（需后端 `bilibili` 代理） |
| `user` | `string` | — | 发送弹幕的用户名 |
| `group` | `string \| number` | — | 会员组（广告投放判断） |
| `maximum` | `number` | 不限制 | 最多加载的弹幕条数 |
| `speedRate` | `number` | `1` | 弹幕滚动速度倍率 |
| `opacity` | `number` | `0.7` | 弹幕透明度 0~1（会被用户本地设置覆盖） |
| `fontSize` | `string` | `'18px'` | 弹幕基准字号 |
| `bottom` | `string` | — | 弹幕区底部间距 |
| `unlimited` | `boolean` | `false` | 海量弹幕（允许同轨道重叠） |
| `blockWords` | `string[]` | `[]` | 发送拦截关键词（与顶层 `blockWords` 合并） |

### subtitle: SubtitleOptions

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | 必填 | 字幕地址（WebVTT） |
| `type` | `string` | — | 字幕类型（暂仅 WebVTT） |
| `fontSize` | `string` | — | 字号 |
| `bottom` | `string` | — | 底部间距 |
| `color` | `string` | — | 颜色 |

### ads: AdsOptions

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `state` | `boolean \| 'on' \| 'off'` | `false` | 广告总开关 |
| `set.state` | `1 \| 2` | `1` | `1`=视频广告，`2`=图片广告 |
| `set.group` | `string \| number` | `2` | 广告范围（会员组阈值，低于该组投放） |
| `set.pic` | `{ time, img, link }` | — | 图片广告：时长(秒)/图片/跳转链接 |
| `set.vod` | `{ url, link }` | — | 视频广告：视频地址/跳转链接 |
| `pause.state` | `boolean \| 'on' \| 'off'` | `false` | 暂停广告开关 |
| `pause.pic` | `string` | `''` | 暂停广告图片 |
| `pause.link` | `string` | `''` | 暂停广告链接 |

### contextmenu: ContextMenuItem[]

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `text` | `string` | 菜单文字 |
| `key` | `string` | 备用标识（text 为空时显示） |
| `link` | `string` | 点击后新窗口打开链接 |
| `click` | `(player) => void` | 点击回调，优先级高于 `link` |

### apiBackend: ApiBackend

自定义弹幕请求实现，内置实现使用 `fetch` + 原项目协议（`code:23 + danmuku`）。需要实现：

| 方法 | 说明 |
| --- | --- |
| `read({ url, success, error })` | 读取弹幕，`success(data: DanmakuItem[])` |
| `send({ url, data, success, error })` | 发送弹幕 |
| `report({ url, success, error })` | 举报弹幕 |

## 弹幕协议（与原项目一致）

```text
GET  /dmku/?ac=get&id=xxx   → {"code":23,"name":"xxx","danum":n,"danmuku":[[time,type,color,cid,text,ip,date,size],...]}
POST /dmku/  JSON           → {"code":23,"danmuku":true}    # 发送 {player,text,color,type,size,time}
GET  /dmku/?ac=so&key=      → 搜索
GET  /dmku/?ac=list         → 分页列表（后台）
GET  /dmku/?ac=report       → 举报
GET  /dmku/?ac=del          → 删除
GET  /bilibili?av=&p=       → B站官方弹幕代理
GET  /bplayer/config        → 播放器公开配置（SDK fetchConfig 使用）
```

## 无后端模式

不配置 `danmaku.api` 时，弹幕按钮保留显示；播放开始或点击发送时会通过 `notice` 提示「未配置 danmaku api」，不会发起任何请求。本地弹幕 `danmaku.draw()` 不受影响。

## 构建

```bash
pnpm build          # 构建 SDK + 后端 + 后台
pnpm build:demo     # 构建演示页
```

SDK 产物在 `packages/bplayer/dist/`：`bplayer.js`（ESM）、`bplayer.umd.cjs`、`bplayer.css`、类型声明 `index.d.ts`。