# js视频字幕库

**Repository Path**: hsmyldk/js-video-caption-library

## Basic Information

- **Project Name**: js视频字幕库
- **Description**: 传入字幕文件内容和video标签,利用canvas展示字幕
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2022-03-01
- **Last Updated**: 2025-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# js视频字幕库

## 介绍
传入字幕文件内容和video标签,利用canvas展示字幕

目前支持[ass,srt,ssa]字幕,可以自定义字幕解析方法

## 功能

支持简繁切换(不全,可以自己改方法)

可以设置字幕字体,颜色,大小,描边,底色

支持ass特殊字幕的位置(有可能越界,具体样子看第三张图片),动效和渐变暂时不支持(有空再加上,大概率鸽了)

## 效果

![只描边](./photos/image-20220301180334205.png)

字幕只设置了颜色和描边,无底纹

![dom元素](./photos/image-20220301180448491.png)

显示字幕的canvas dom

![特殊字幕](./photos/image-20220301181302453.png)

特殊字幕还是有点问题,因为字体大小是使用的默认设置,而不是这条字幕的设置,所以越界了,有空把它改了吧..

## 使用:

### 新建

```javascript
//创建字幕,video元素和字幕内容必传,其他选传
let subtitle = new H_Subtitle({video:videoDom,subtitleText:'字幕内容......'})

```

### 新建时设置属性(全)

```javascript
let subtitle = new H_Subtitle({
    			//subtitleScOrTc 使用简体?简体:繁体
    			subtitleUseSc: true,
    			//视频元素
                video: videoDom,
    			//字幕内容
                subtitleText: res,
    			//给canvas设置的属性,目的是让canvas在video的前边且与video重叠
                canvasStyle: 'position: absolute;',
                subtitleStyle: {
                  //字幕颜色
                  fontColor: '#FFFFFF',
                  //字幕背景色
                  // backgroundColor: '#3B3B3B90',
                  // backgroundColor: '#000000',
                  //字幕位置 仅支持百分比,5 就是字幕底边距离video的底边 5% 支持小数
                  subtitlePosition: '5',
                  //字幕字的大小 仅支持百分比,5 就是指字的高度为video高度的 5% 支持小数
                  subtitleHeight: '5',
                  //默认的字体样式, 字体大小会自动计算并拼接,这里不需要填上多少px
                  font: 'YouYuan',
                  // -未实现- 字幕显示样式 [center 居中,left 居左,right 居右]
                  textAlign: 'center',
                  // 自动换行
                  autoWrap: true,
                  //字幕描边宽度
                  borderWidth: 3,
                  //字幕描边颜色
                  borderColor: '#000000'
                }
              })
```

### 重新设置字幕字体

```javascript
//设置字体为幼圆
subtitle.setFont('YouYuan')
```

#### 设置字体时注意事项:

设置的字体一定要在页面上使用过或直接就能用的

原因:浏览器的字体懒加载,只有页面上使用这个字体时才去加载,所以canvas使用这个字体时如果网页需要加载字体,而这时canvas的上下文已经创建好了,就会导致字体不生效

例如:我要使用**思源宋体**而网页上没有用过这个,直接设置就会导致显示的字体为canvas默认的**Arial**

正确用法是在canvas使用此字体之前将此字体加载到浏览器

例:

```javascript
//纯js法:

let fontName = 'siYuanSongTi';
const font = new FontFace(fontName, 'url(' ../fonts/SourceHanSerifCN-SemiBold-7.otf ')')
//加载字体
font.load().then(f => {
  //设置字体进页面
  document.fonts.add(f)
}).then((e) => {
  //设置字幕字体
  subtitle.setFont(fontName)
})
```

### 获取字幕配置

```javascript
subtitle.getSetting()
//返回此库的所有设置,对于内容,尽量不要修改
```

### 重新加载字幕

```javascript
//重新加载字幕
//video video元素 可不传
//subtitleText 字幕内容 可不传
subtitle.reload(video, subtitleText)
```

### 设置字幕样式

```javascript
  /**
   * 热设置全局字幕样式
   * @param fontColor 字幕颜色
   * @param backgroundColor 背景 [null]啥也不干 [false]取消显示 [颜色字符串]按颜色显示
   * @param borderColor 描边宽度
   * @param borderWidth 描边颜色 [null]啥也不干 [false]取消显示 [颜色字符串]按颜色显示
   */
subtitle.setStyle({fontColor, backgroundColor, borderWidth, borderColor})
```

### 简体繁体

这个仅支持在初始化时使用简体还是繁体,使用的话看前边的 [新建时设置属性(全)]

这个东西的原理就是把对应的字的简繁对应写出来就完事了

## 回调事件

```javascript
//回调方法s
functionEvens: {
  //初始化canvas后回调
  afterInitCanvas: null,
  //字幕创建成功后回调
  afterCreated: null,
  //canvas重设大小后回调 [重设大小事件只有在视频播放时才会触发]
  afterCanvasReSize: null
},
```

|      方法名       |                            时机                             | 参数         | 参数解释                          |
| :---------------: | :---------------------------------------------------------: | ------------ | --------------------------------- |
|  afterInitCanvas  |                     初始化canvas后回调                      | setting      | 当前实例的配置                    |
|   afterCreated    |                     字幕创建成功后回调                      | setting      | 当前实例的配置                    |
| afterCanvasReSize | canvas重设大小后回调 [重设大小事件只有在视频播放时才会触发] | size,setting | 计算出的canvas宽高,当前实例的配置 |

## 自定义字幕解析方法

在创建实例时将方法传进去

例:

```javascript
//解析方法,例如这个方法是解析ass的
let fun = res=>{
	let subArray = [];
	//......进行解析
    //对于subArray内容的解释,如果看不懂可以参考源码的默认方法 源码中搜: defaultSubtitleFunctions
    {
        //字幕出现的开始时间,文件中必定有
        startTime,
        //字幕消失的时间,
        endTime,
        //这条字母的内容
        subText: '哈哈哈哈',
        //特效字幕指定出现位置,默认的无需设置,null就可以,但是只要设置了就一定xy都要有
        //就是个二维坐标的位置
        pos: {x,y}
     }
    
    //
	return subArray;
}
//创建字幕,video元素和字幕内容必传,其他选传
let subtitle = new H_Subtitle({video:videoDom,
                               subtitleText:'字幕内容......',
                               //这里就是自定义的解析方法,优先使用自定义的,没有则使用自带的
                               //因为ass字幕的开头一定是[Script Info],所以key就写'[Script Info]'
                               //key就是写字幕文件的开头
                               subtitleFunctions:[{key:'[Script Info]',fun:fun}]})
```



## 项目中使用例子请看这个vue文件:

[src/views/videoPlayer.vue · hsmyldk/网络视频播放器前端 - 码云 - 开源中国 (gitee.com)](https://gitee.com/hsmyldk/ruoyi-ui/blob/master/src/views/videoPlayer.vue)

## PS:

**由于字幕的前进是监听的video的播放方法,字幕的展示类似于一帧一帧的,所以在视频暂停时字幕的所有操作是暂停的**