音视频(FFmpeg)
用 lingtools 提供的 FFmpeg 处理音视频:转码、压缩、裁剪、提取音频、截帧。插件不用自己打包 FFmpeg。需要 ffmpeg 权限。
用户第一次用到时,lingtools 会弹窗下载 FFmpeg(9.0.2,含 ffprobe),之后一直可用。用户关掉下载窗口时调用以 unavailable 失败。
runFFmpeg
ts
runFFmpeg(args: string[], onProgress?: (progress) => void): FFmpegProcess
runFFmpeg(args: string[], options?: { onProgress?, onLog?, duration? }): FFmpegProcessargs 是 ffmpeg 的命令行参数(不含 ffmpeg 本身)。返回值可以 await,另有两个方法:kill() 强制结束(以 aborted reject,不保留输出)、quit() 请求正常收尾(相当于按 q,保留已输出的内容)。
ts
const task = window.ling.runFFmpeg(
['-i', input, '-vf', 'scale=1280:-2', '-c:v', 'libx264', '-crf', '28', '-y', output],
{
onProgress: (p) => (percent.value = p.percent ?? 0),
onLog: (text) => console.log(text),
},
)
cancelButton.onclick = () => task.kill()
await task进度 progress:percent(0–100,知道总时长时才有)、time(已处理的媒体时间)、frame、fps、speed、size、bitrate。裁剪、变速时 ffmpeg 不知道输出时长,传 duration(秒)让 percent 准确。
参数限制
为了不让插件借 FFmpeg 读写任意文件,lingtools 会检查参数:
- 输入(
-i)和输出都必须是本机文件的绝对路径,并按文件权限规则检查(插件目录外的输入要fs.read、输出要fs;用户选择的文件免声明); - 只能有一个输出,且必须是最后一个参数;
- 禁止读写额外文件的选项,如
-progress、-vstats_file、-passlogfile、-filter_complex_script、预设文件、-segment_list、-hls_*; - 输入只能读本机文件,不能读网络地址。
违反时以 invalid_params 或 forbidden 失败。
输出
- 先写临时文件,成功后改名。目标已存在且参数里没有
-y时不执行(data.code为EEXIST)。 - 输出文件名含
%d/%03d(图片序列、分段)时,所在目录必须还不存在,成功后整个目录出现。 - ffmpeg 非零退出时以
ffmpeg_failed失败,error.data为{ exitCode, log }(stderr 最后 20 行)。 - 同时最多运行 4 个,超出的排队。页面或插件关闭时正在运行的任务会被结束。
ffmpeg.probe
ts
ffmpeg.probe(path: string): Promise<MediaProbe>读媒体信息(ffprobe 的整理结果):
ts
const info = await window.ling.ffmpeg.probe(file)
// {
// formatName: 'mov,mp4,m4a,3gp,3g2,mj2', duration: 63.2, size: 18834211, bitRate: 2384000,
// streams: [
// { index: 0, type: 'video', codec: 'h264', width: 1920, height: 1080, frameRate: 29.97, rotation: 0, … },
// { index: 1, type: 'audio', codec: 'aac', sampleRate: 48000, channels: 2, … },
// ],
// }视频流的 width / height 是编码尺寸,rotation 不为 0 时显示需要旋转。文件不存在为 not_found,不是媒体文件为 ffmpeg_failed。
ffmpeg.status
ts
ffmpeg.status(): Promise<{ installed: boolean; version: string; downloadSize: number }>查询是否已安装,不会触发下载。可以在第一次使用前提示用户「需要下载约 xx MB」。