@happyvertical/video 0.74.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENT.md ADDED
@@ -0,0 +1,33 @@
1
+ # @happyvertical/video
2
+
3
+ <!-- BEGIN AGENT:GENERATED -->
4
+ ## Purpose
5
+ Video processing utilities with adapter pattern for composition and transcoding
6
+
7
+ ## Package Map
8
+ - Package: `@happyvertical/video`
9
+ - Hierarchy path: `@happyvertical/sdk > packages > video`
10
+ - Workspace position: `29 of 30` local packages
11
+ - Internal dependencies: `@happyvertical/images`, `@happyvertical/logger`, `@happyvertical/utils`
12
+ - Internal dependents: none
13
+ - Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
14
+
15
+ ## Build & Test
16
+ ```bash
17
+ pnpm --filter @happyvertical/video build
18
+ pnpm --filter @happyvertical/video test
19
+ pnpm --filter @happyvertical/video clean
20
+ ```
21
+
22
+ ## Agent Correction Loops
23
+ - If module resolution or export errors mention a workspace dependency, build the dependency first (`pnpm --filter @happyvertical/images build`, `pnpm --filter @happyvertical/logger build`, `pnpm --filter @happyvertical/utils build`) and then rerun `pnpm --filter @happyvertical/video build`.
24
+ - If tests or exports fail after API, type, or bundle changes, run `pnpm --filter @happyvertical/video clean` followed by `pnpm --filter @happyvertical/video build` and `pnpm --filter @happyvertical/video test`.
25
+ - If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
26
+
27
+ ## Ecosystem Relationships
28
+ - Provides: Video processing utilities with adapter pattern for composition and transcoding
29
+ - Implements: none
30
+ - Requires: @happyvertical/images, @happyvertical/logger, @happyvertical/utils, sharp
31
+ - Stability: stable (Primary package surface is described as implemented and production-oriented.)
32
+ <!-- END AGENT:GENERATED -->
33
+
package/LICENSE ADDED
@@ -0,0 +1,7 @@
1
+ Copyright <2025> <Happy Vertical Corporation>
2
+
3
+ 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:
4
+
5
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6
+
7
+ 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 ADDED
@@ -0,0 +1,462 @@
1
+ ---
2
+ id: video
3
+ title: "@happyvertical/video: Video Processing"
4
+ sidebar_label: "@happyvertical/video"
5
+ sidebar_position: 12
6
+ ---
7
+
8
+ # @happyvertical/video
9
+
10
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
11
+
12
+ Video processing utilities with adapter pattern for composition and transcoding in the HAVE SDK.
13
+
14
+ ## Overview
15
+
16
+ The `@happyvertical/video` package provides a unified interface for video processing operations using FFmpeg. It supports video composition, transcoding, overlay placement, thumbnail extraction, and lower-third generation for news-style video production.
17
+
18
+ ## Features
19
+
20
+ - **Video Composition**: Combine video, audio, and overlays
21
+ - **Transcoding**: Convert between formats and adjust quality
22
+ - **Thumbnail Extraction**: Extract frames at specific timestamps
23
+ - **Lower-Third Overlays**: News-style name/title graphics
24
+ - **Image Overlays**: Position logos and watermarks
25
+ - **Audio Mixing**: Combine multiple audio tracks
26
+ - **Metadata Extraction**: Get duration, resolution, codec info
27
+ - **Format Conversion**: Support for MP4, WebM, MOV, and more
28
+ - **Type-Safe**: Full TypeScript support
29
+
30
+ ## Installation
31
+
32
+ ```bash
33
+ # Install with bun (recommended)
34
+ bun add @happyvertical/video
35
+
36
+ # Or with npm
37
+ npm install @happyvertical/video
38
+
39
+ # Or with pnpm
40
+ pnpm add @happyvertical/video
41
+ ```
42
+
43
+ ### Prerequisites
44
+
45
+ FFmpeg must be installed and available in your system PATH:
46
+
47
+ ```bash
48
+ # macOS
49
+ brew install ffmpeg
50
+
51
+ # Ubuntu/Debian
52
+ sudo apt install ffmpeg
53
+
54
+ # Windows (with Chocolatey)
55
+ choco install ffmpeg
56
+ ```
57
+
58
+ ## Quick Start
59
+
60
+ ### Basic Usage
61
+
62
+ ```typescript
63
+ import { FFmpegProcessor } from '@happyvertical/video';
64
+
65
+ const processor = new FFmpegProcessor();
66
+
67
+ // Get video metadata
68
+ const metadata = await processor.getMetadata('input.mp4');
69
+ console.log(`Duration: ${metadata.duration}s`);
70
+ console.log(`Resolution: ${metadata.width}x${metadata.height}`);
71
+ console.log(`FPS: ${metadata.fps}`);
72
+
73
+ // Extract thumbnail
74
+ const thumbnail = await processor.extractFrame('input.mp4', 2.0, {
75
+ format: 'jpg',
76
+ width: 1280,
77
+ quality: 90,
78
+ });
79
+ fs.writeFileSync('thumbnail.jpg', thumbnail);
80
+ ```
81
+
82
+ ### Video Composition
83
+
84
+ ```typescript
85
+ const output = await processor.compose({
86
+ baseVideo: 'input.mp4',
87
+ audio: 'narration.mp3',
88
+ overlays: [
89
+ {
90
+ type: 'image',
91
+ content: 'logo.png',
92
+ position: { x: 'right', y: 'top', padding: 20 },
93
+ opacity: 0.8,
94
+ },
95
+ {
96
+ type: 'text',
97
+ content: 'BREAKING NEWS',
98
+ position: { x: 'center', y: 'bottom', padding: 50 },
99
+ style: {
100
+ fontSize: 48,
101
+ fontColor: 'white',
102
+ backgroundColor: 'red',
103
+ },
104
+ },
105
+ ],
106
+ outputFormat: 'mp4',
107
+ quality: 20,
108
+ });
109
+
110
+ fs.writeFileSync('output.mp4', output);
111
+ ```
112
+
113
+ ### Lower-Third Graphics
114
+
115
+ ```typescript
116
+ // Add news-style lower-third with name and title
117
+ const output = await processor.addLowerThird('input.mp4', {
118
+ title: 'John Smith',
119
+ subtitle: 'Senior Correspondent',
120
+ style: 'news',
121
+ primaryColor: '#1a1a1a',
122
+ accentColor: '#cc0000',
123
+ duration: 5, // seconds
124
+ startTime: 0,
125
+ fadeIn: 0.5,
126
+ fadeOut: 0.5,
127
+ });
128
+ ```
129
+
130
+ ### Transcoding for Social Platforms
131
+
132
+ ```typescript
133
+ // YouTube Shorts (9:16 vertical)
134
+ const youtubeShort = await processor.transcode('input.mp4', {
135
+ format: 'mp4',
136
+ width: 1080,
137
+ height: 1920,
138
+ video: {
139
+ codec: 'h264',
140
+ preset: 'medium',
141
+ crf: 23,
142
+ },
143
+ audio: {
144
+ codec: 'aac',
145
+ bitrate: '128k',
146
+ },
147
+ });
148
+
149
+ // Web-optimized (16:9 horizontal)
150
+ const webVideo = await processor.transcode('input.mp4', {
151
+ format: 'mp4',
152
+ width: 1920,
153
+ height: 1080,
154
+ video: {
155
+ codec: 'h264',
156
+ preset: 'slow',
157
+ crf: 20,
158
+ },
159
+ audio: {
160
+ codec: 'aac',
161
+ bitrate: '192k',
162
+ },
163
+ });
164
+ ```
165
+
166
+ ## API Reference
167
+
168
+ ### FFmpegProcessor
169
+
170
+ The main processor class for video operations.
171
+
172
+ #### Constructor
173
+
174
+ ```typescript
175
+ new FFmpegProcessor(options?: VideoProcessorOptions)
176
+ ```
177
+
178
+ | Option | Type | Default | Description |
179
+ |--------|------|---------|-------------|
180
+ | `ffmpegPath` | `string` | `'ffmpeg'` | Path to FFmpeg binary |
181
+ | `ffprobePath` | `string` | `'ffprobe'` | Path to FFprobe binary |
182
+ | `tempDir` | `string` | system temp | Directory for temp files |
183
+ | `timeout` | `number` | `300000` | Processing timeout (ms) |
184
+
185
+ #### Methods
186
+
187
+ ##### getMetadata
188
+
189
+ Get video file metadata.
190
+
191
+ ```typescript
192
+ async getMetadata(video: Buffer | string): Promise<VideoMetadata>
193
+ ```
194
+
195
+ ##### extractFrame
196
+
197
+ Extract a single frame as an image.
198
+
199
+ ```typescript
200
+ async extractFrame(
201
+ video: Buffer | string,
202
+ timestamp: number,
203
+ options?: ExtractFrameOptions
204
+ ): Promise<Buffer>
205
+ ```
206
+
207
+ | Option | Type | Default | Description |
208
+ |--------|------|---------|-------------|
209
+ | `format` | `'jpg' \| 'png' \| 'webp'` | `'jpg'` | Output format |
210
+ | `width` | `number` | original | Output width |
211
+ | `height` | `number` | original | Output height |
212
+ | `quality` | `number` | `85` | JPEG quality (1-100) |
213
+
214
+ ##### compose
215
+
216
+ Compose video with overlays and audio.
217
+
218
+ ```typescript
219
+ async compose(options: ComposeOptions): Promise<Buffer>
220
+ ```
221
+
222
+ ##### addLowerThird
223
+
224
+ Add lower-third graphic overlay.
225
+
226
+ ```typescript
227
+ async addLowerThird(
228
+ video: Buffer | string,
229
+ config: LowerThirdConfig
230
+ ): Promise<Buffer>
231
+ ```
232
+
233
+ ##### transcode
234
+
235
+ Convert video format and adjust quality.
236
+
237
+ ```typescript
238
+ async transcode(
239
+ video: Buffer | string,
240
+ options: TranscodeOptions
241
+ ): Promise<Buffer>
242
+ ```
243
+
244
+ ##### addOverlay
245
+
246
+ Add image or text overlay to video.
247
+
248
+ ```typescript
249
+ async addOverlay(
250
+ video: Buffer | string,
251
+ overlay: OverlayConfig
252
+ ): Promise<Buffer>
253
+ ```
254
+
255
+ ### Types
256
+
257
+ ```typescript
258
+ interface VideoMetadata {
259
+ duration: number; // seconds
260
+ width: number;
261
+ height: number;
262
+ fps: number;
263
+ codec: string;
264
+ bitrate?: number;
265
+ audioCodec?: string;
266
+ audioBitrate?: number;
267
+ audioSampleRate?: number;
268
+ }
269
+
270
+ interface ComposeOptions {
271
+ baseVideo: Buffer | string;
272
+ audio?: Buffer | string;
273
+ overlays?: OverlayConfig[];
274
+ outputFormat?: VideoFormat;
275
+ quality?: number; // CRF value (lower = better)
276
+ }
277
+
278
+ interface OverlayConfig {
279
+ type: 'image' | 'text';
280
+ content: Buffer | string;
281
+ position: OverlayPosition;
282
+ opacity?: number; // 0-1
283
+ startTime?: number;
284
+ duration?: number;
285
+ fadeIn?: number;
286
+ fadeOut?: number;
287
+ style?: TextOverlayOptions;
288
+ }
289
+
290
+ interface OverlayPosition {
291
+ x: number | 'left' | 'center' | 'right';
292
+ y: number | 'top' | 'center' | 'bottom';
293
+ padding?: number;
294
+ }
295
+
296
+ interface LowerThirdConfig {
297
+ title: string;
298
+ subtitle?: string;
299
+ style?: 'news' | 'minimal' | 'modern';
300
+ primaryColor?: string;
301
+ accentColor?: string;
302
+ textColor?: string;
303
+ duration?: number;
304
+ startTime?: number;
305
+ fadeIn?: number;
306
+ fadeOut?: number;
307
+ }
308
+
309
+ interface TranscodeOptions {
310
+ format: VideoFormat;
311
+ width?: number;
312
+ height?: number;
313
+ video?: VideoCodecOptions;
314
+ audio?: AudioCodecOptions;
315
+ }
316
+
317
+ interface VideoCodecOptions {
318
+ codec: 'h264' | 'h265' | 'vp9' | 'av1';
319
+ preset?: 'ultrafast' | 'fast' | 'medium' | 'slow' | 'veryslow';
320
+ crf?: number; // 0-51 (lower = better quality)
321
+ bitrate?: string; // e.g., '5M'
322
+ }
323
+
324
+ interface AudioCodecOptions {
325
+ codec: 'aac' | 'mp3' | 'opus';
326
+ bitrate?: string; // e.g., '128k'
327
+ sampleRate?: number; // e.g., 48000
328
+ }
329
+
330
+ type VideoFormat = 'mp4' | 'webm' | 'mov' | 'avi' | 'mkv';
331
+ ```
332
+
333
+ ## Use Cases
334
+
335
+ ### News Video Production Pipeline
336
+
337
+ ```typescript
338
+ import { FFmpegProcessor } from '@happyvertical/video';
339
+
340
+ async function processNewsVideo(rawVideo: string, anchorName: string) {
341
+ const processor = new FFmpegProcessor();
342
+
343
+ // 1. Add lower-third with anchor name
344
+ const withLowerThird = await processor.addLowerThird(rawVideo, {
345
+ title: anchorName,
346
+ subtitle: 'News Correspondent',
347
+ style: 'news',
348
+ primaryColor: '#1a237e',
349
+ accentColor: '#c62828',
350
+ duration: 5,
351
+ startTime: 0,
352
+ });
353
+
354
+ // 2. Add station logo
355
+ const withLogo = await processor.addOverlay(withLowerThird, {
356
+ type: 'image',
357
+ content: 'station-logo.png',
358
+ position: { x: 'right', y: 'top', padding: 20 },
359
+ opacity: 0.9,
360
+ });
361
+
362
+ // 3. Create multiple formats for distribution
363
+ const youtubeShort = await processor.transcode(withLogo, {
364
+ format: 'mp4',
365
+ width: 1080,
366
+ height: 1920,
367
+ video: { codec: 'h264', preset: 'medium', crf: 23 },
368
+ });
369
+
370
+ const webVersion = await processor.transcode(withLogo, {
371
+ format: 'mp4',
372
+ width: 1920,
373
+ height: 1080,
374
+ video: { codec: 'h264', preset: 'medium', crf: 20 },
375
+ });
376
+
377
+ // 4. Extract thumbnail
378
+ const thumbnail = await processor.extractFrame(withLogo, 2.0, {
379
+ format: 'jpg',
380
+ width: 1280,
381
+ quality: 90,
382
+ });
383
+
384
+ return { youtubeShort, webVersion, thumbnail };
385
+ }
386
+ ```
387
+
388
+ ### Batch Thumbnail Generation
389
+
390
+ ```typescript
391
+ async function generateThumbnails(videos: string[], timestamps: number[] = [2.0]) {
392
+ const processor = new FFmpegProcessor();
393
+ const thumbnails = [];
394
+
395
+ for (const video of videos) {
396
+ for (const timestamp of timestamps) {
397
+ const thumbnail = await processor.extractFrame(video, timestamp, {
398
+ format: 'webp',
399
+ width: 1280,
400
+ quality: 85,
401
+ });
402
+ thumbnails.push({
403
+ video,
404
+ timestamp,
405
+ data: thumbnail,
406
+ });
407
+ }
408
+ }
409
+
410
+ return thumbnails;
411
+ }
412
+ ```
413
+
414
+ ## Best Practices
415
+
416
+ ### Memory Management
417
+
418
+ ```typescript
419
+ // For large videos, use file paths instead of buffers
420
+ const output = await processor.transcode('/path/to/large-video.mp4', {
421
+ format: 'mp4',
422
+ // ...options
423
+ });
424
+
425
+ // Write output to file instead of keeping in memory
426
+ fs.writeFileSync('/path/to/output.mp4', output);
427
+ ```
428
+
429
+ ### Quality vs Size Trade-offs
430
+
431
+ ```typescript
432
+ // High quality (larger file)
433
+ { video: { codec: 'h264', preset: 'slow', crf: 18 } }
434
+
435
+ // Balanced (recommended)
436
+ { video: { codec: 'h264', preset: 'medium', crf: 23 } }
437
+
438
+ // Fast encoding (lower quality)
439
+ { video: { codec: 'h264', preset: 'fast', crf: 28 } }
440
+ ```
441
+
442
+ ### Platform-Specific Encoding
443
+
444
+ ```typescript
445
+ // YouTube recommended settings
446
+ {
447
+ format: 'mp4',
448
+ video: { codec: 'h264', preset: 'slow', crf: 18 },
449
+ audio: { codec: 'aac', bitrate: '384k' },
450
+ }
451
+
452
+ // Twitter/X recommended settings
453
+ {
454
+ format: 'mp4',
455
+ video: { codec: 'h264', preset: 'medium', crf: 23 },
456
+ audio: { codec: 'aac', bitrate: '128k' },
457
+ }
458
+ ```
459
+
460
+ ## License
461
+
462
+ This package is part of the HAVE SDK and is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.