编号:视频 标题:"@happyvertical/video:视频处理" 侧边栏 标签: "@ happyvertical/video" 侧边栏( p): 12
@ 快乐的垂直/视频
在HARE SDK中具有可适配器模式的视频处理功能,用于组成和转码.
概览
这个 @happyvertical/video 软件包为使用FFmpeg的视频处理操作提供统一接口. 它支持视频组成,转码,上线布置,缩略图提取,以及下第三代用于新闻风格的视频制作.
特征
- 视频组成: 合并视频、音频和覆盖
- 转码: 在格式之间转换并调整质量
- 缩略图提取: 在特定时间戳上提取帧
- 下三级重叠: 新闻风格名称/标题图形
- 图像重叠: 位置标志和水印
- 音频混合: 合并多个音频音轨
- 元数据提取: 获取持续时间、 分辨率、 编码信息
- 格式转换: 支持 MP4, WebM, MOV 等
- 类型安全: 完整类型脚本支持
安装
# Install with bun (recommended)
bun add @happyvertical/video
# Or with npm
npm install @happyvertical/video
# Or with pnpm
pnpm add @happyvertical/video
先决条件
FFmpeg 必须在您的系统中安装和提供 PATH :
# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt install ffmpeg
# Windows (with Chocolatey)
choco install ffmpeg
快速启动
基本用途
import { FFmpegProcessor } from '@happyvertical/video';
const processor = new FFmpegProcessor();
// Get video metadata
const metadata = await processor.getMetadata('input.mp4');
console.log(`Duration: ${metadata.duration}s`);
console.log(`Resolution: ${metadata.width}x${metadata.height}`);
console.log(`FPS: ${metadata.fps}`);
// Extract thumbnail
const thumbnail = await processor.extractFrame('input.mp4', 2.0, {
format: 'jpg',
width: 1280,
quality: 90,
});
fs.writeFileSync('thumbnail.jpg', thumbnail);
视频组成
const output = await processor.compose({
baseVideo: 'input.mp4',
audio: 'narration.mp3',
overlays: [
{
type: 'image',
content: 'logo.png',
position: { x: 'right', y: 'top', padding: 20 },
opacity: 0.8,
},
{
type: 'text',
content: 'BREAKING NEWS',
position: { x: 'center', y: 'bottom', padding: 50 },
style: {
fontSize: 48,
fontColor: 'white',
backgroundColor: 'red',
},
},
],
outputFormat: 'mp4',
quality: 20,
});
fs.writeFileSync('output.mp4', output);
下三层图形
// Add news-style lower-third with name and title
const output = await processor.addLowerThird('input.mp4', {
title: 'John Smith',
subtitle: 'Senior Correspondent',
style: 'news',
primaryColor: '#1a1a1a',
accentColor: '#cc0000',
duration: 5, // seconds
startTime: 0,
fadeIn: 0.5,
fadeOut: 0.5,
});
社会平台转码
// YouTube Shorts (9:16 vertical)
const youtubeShort = await processor.transcode('input.mp4', {
format: 'mp4',
width: 1080,
height: 1920,
video: {
codec: 'h264',
preset: 'medium',
crf: 23,
},
audio: {
codec: 'aac',
bitrate: '128k',
},
});
// Web-optimized (16:9 horizontal)
const webVideo = await processor.transcode('input.mp4', {
format: 'mp4',
width: 1920,
height: 1080,
video: {
codec: 'h264',
preset: 'slow',
crf: 20,
},
audio: {
codec: 'aac',
bitrate: '192k',
},
});
API 参考
FFmpeg 处理器
视频业务的主要处理器类.
构造器
new FFmpegProcessor(options?: VideoProcessorOptions)
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
ffmpegPath | string | 'ffmpeg' | FFmpeg 二进制路径 |
ffprobePath | string | 'ffprobe' | FF Probe 二进制路径 |
tempDir | string | 系统临时 | 临时文件目录 |
timeout | number | 300000 | 处理超时( 毫秒) |
方法
获取元数据
获取视频文件元数据 .
async getMetadata(video: Buffer | string): Promise<VideoMetadata>
节选Frame
取出一帧为图像.
async extractFrame(
video: Buffer | string,
timestamp: number,
options?: ExtractFrameOptions
): Promise<Buffer>
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
format | 'jpg' | 'png' | 'webp' | 'jpg' | 输出格式 |
width | number | 原文 | 输出宽度 |
height | number | 原文 | 输出高度 |
quality | number | 85 | JPEG 质量(1-100) |
编曲
以覆盖和音频来作曲视频.
async compose(options: ComposeOptions): Promise<Buffer>
添加倒数第三
添加下第三图形覆盖.
async addLowerThird(
video: Buffer | string,
config: LowerThirdConfig
): Promise<Buffer>
转码
转换视频格式并调整质量.
async transcode(
video: Buffer | string,
options: TranscodeOptions
): Promise<Buffer>
添加重叠
将图像或文本覆盖到视频中 .
async addOverlay(
video: Buffer | string,
overlay: OverlayConfig
): Promise<Buffer>
类型
interface VideoMetadata {
duration: number; // seconds
width: number;
height: number;
fps: number;
codec: string;
bitrate?: number;
audioCodec?: string;
audioBitrate?: number;
audioSampleRate?: number;
}
interface ComposeOptions {
baseVideo: Buffer | string;
audio?: Buffer | string;
overlays?: OverlayConfig[];
outputFormat?: VideoFormat;
quality?: number; // CRF value (lower = better)
}
interface OverlayConfig {
type: 'image' | 'text';
content: Buffer | string;
position: OverlayPosition;
opacity?: number; // 0-1
startTime?: number;
duration?: number;
fadeIn?: number;
fadeOut?: number;
style?: TextOverlayOptions;
}
interface OverlayPosition {
x: number | 'left' | 'center' | 'right';
y: number | 'top' | 'center' | 'bottom';
padding?: number;
}
interface LowerThirdConfig {
title: string;
subtitle?: string;
style?: 'news' | 'minimal' | 'modern';
primaryColor?: string;
accentColor?: string;
textColor?: string;
duration?: number;
startTime?: number;
fadeIn?: number;
fadeOut?: number;
}
interface TranscodeOptions {
format: VideoFormat;
width?: number;
height?: number;
video?: VideoCodecOptions;
audio?: AudioCodecOptions;
}
interface VideoCodecOptions {
codec: 'h264' | 'h265' | 'vp9' | 'av1';
preset?: 'ultrafast' | 'fast' | 'medium' | 'slow' | 'veryslow';
crf?: number; // 0-51 (lower = better quality)
bitrate?: string; // e.g., '5M'
}
interface AudioCodecOptions {
codec: 'aac' | 'mp3' | 'opus';
bitrate?: string; // e.g., '128k'
sampleRate?: number; // e.g., 48000
}
type VideoFormat = 'mp4' | 'webm' | 'mov' | 'avi' | 'mkv';
使用大小写
新闻录像制作管道
import { FFmpegProcessor } from '@happyvertical/video';
async function processNewsVideo(rawVideo: string, anchorName: string) {
const processor = new FFmpegProcessor();
// 1. Add lower-third with anchor name
const withLowerThird = await processor.addLowerThird(rawVideo, {
title: anchorName,
subtitle: 'News Correspondent',
style: 'news',
primaryColor: '#1a237e',
accentColor: '#c62828',
duration: 5,
startTime: 0,
});
// 2. Add station logo
const withLogo = await processor.addOverlay(withLowerThird, {
type: 'image',
content: 'station-logo.png',
position: { x: 'right', y: 'top', padding: 20 },
opacity: 0.9,
});
// 3. Create multiple formats for distribution
const youtubeShort = await processor.transcode(withLogo, {
format: 'mp4',
width: 1080,
height: 1920,
video: { codec: 'h264', preset: 'medium', crf: 23 },
});
const webVersion = await processor.transcode(withLogo, {
format: 'mp4',
width: 1920,
height: 1080,
video: { codec: 'h264', preset: 'medium', crf: 20 },
});
// 4. Extract thumbnail
const thumbnail = await processor.extractFrame(withLogo, 2.0, {
format: 'jpg',
width: 1280,
quality: 90,
});
return { youtubeShort, webVersion, thumbnail };
}
批量缩略图生成
async function generateThumbnails(videos: string[], timestamps: number[] = [2.0]) {
const processor = new FFmpegProcessor();
const thumbnails = [];
for (const video of videos) {
for (const timestamp of timestamps) {
const thumbnail = await processor.extractFrame(video, timestamp, {
format: 'webp',
width: 1280,
quality: 85,
});
thumbnails.push({
video,
timestamp,
data: thumbnail,
});
}
}
return thumbnails;
}
最佳做法
内存管理
// For large videos, use file paths instead of buffers
const output = await processor.transcode('/path/to/large-video.mp4', {
format: 'mp4',
// ...options
});
// Write output to file instead of keeping in memory
fs.writeFileSync('/path/to/output.mp4', output);
质量与大小权衡
// High quality (larger file)
{ video: { codec: 'h264', preset: 'slow', crf: 18 } }
// Balanced (recommended)
{ video: { codec: 'h264', preset: 'medium', crf: 23 } }
// Fast encoding (lower quality)
{ video: { codec: 'h264', preset: 'fast', crf: 28 } }
平台特定编码
// YouTube recommended settings
{
format: 'mp4',
video: { codec: 'h264', preset: 'slow', crf: 18 },
audio: { codec: 'aac', bitrate: '384k' },
}
// Twitter/X recommended settings
{
format: 'mp4',
video: { codec: 'h264', preset: 'medium', crf: 23 },
audio: { codec: 'aac', bitrate: '128k' },
}
许可证
这个包是HE SDK的一部分,根据麻省理工学院的许可证获得许可——见 自由主义 详细文件.