@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 +33 -0
- package/LICENSE +7 -0
- package/README.md +462 -0
- package/dist/index.d.ts +815 -0
- package/dist/index.js +1176 -0
- package/dist/index.js.map +1 -0
- package/metadata.json +32 -0
- package/package.json +56 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,815 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @happyvertical/video
|
|
3
|
+
*
|
|
4
|
+
* Video processing utilities with adapter pattern for composition and transcoding.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```typescript
|
|
8
|
+
* import { FFmpegProcessor } from '@happyvertical/video';
|
|
9
|
+
*
|
|
10
|
+
* const processor = new FFmpegProcessor();
|
|
11
|
+
*
|
|
12
|
+
* // Get video metadata
|
|
13
|
+
* const metadata = await processor.getMetadata('input.mp4');
|
|
14
|
+
* console.log(`Duration: ${metadata.duration}s, Resolution: ${metadata.width}x${metadata.height}`);
|
|
15
|
+
*
|
|
16
|
+
* // Extract thumbnail at 2 seconds
|
|
17
|
+
* const thumbnail = await processor.extractFrame('input.mp4', 2.0, {
|
|
18
|
+
* format: 'jpg',
|
|
19
|
+
* width: 1280,
|
|
20
|
+
* quality: 90,
|
|
21
|
+
* });
|
|
22
|
+
* fs.writeFileSync('thumbnail.jpg', thumbnail);
|
|
23
|
+
*
|
|
24
|
+
* // Add lower-third overlay
|
|
25
|
+
* const output = await processor.addLowerThird('input.mp4', {
|
|
26
|
+
* title: 'John Smith',
|
|
27
|
+
* subtitle: 'Senior Correspondent',
|
|
28
|
+
* style: 'news',
|
|
29
|
+
* primaryColor: '#1a1a1a',
|
|
30
|
+
* accentColor: '#cc0000',
|
|
31
|
+
* duration: 5,
|
|
32
|
+
* startTime: 0,
|
|
33
|
+
* });
|
|
34
|
+
*
|
|
35
|
+
* // Compose video with multiple operations
|
|
36
|
+
* const composed = await processor.compose({
|
|
37
|
+
* baseVideo: 'input.mp4',
|
|
38
|
+
* audio: 'narration.mp3',
|
|
39
|
+
* overlays: [
|
|
40
|
+
* {
|
|
41
|
+
* type: 'image',
|
|
42
|
+
* content: 'logo.png',
|
|
43
|
+
* position: { x: 'right', y: 'top', padding: 20 },
|
|
44
|
+
* opacity: 0.8,
|
|
45
|
+
* },
|
|
46
|
+
* ],
|
|
47
|
+
* outputFormat: 'mp4',
|
|
48
|
+
* quality: 20,
|
|
49
|
+
* });
|
|
50
|
+
*
|
|
51
|
+
* // Transcode for different platforms
|
|
52
|
+
* const youtubeShort = await processor.transcode('input.mp4', {
|
|
53
|
+
* format: 'mp4',
|
|
54
|
+
* width: 1080,
|
|
55
|
+
* height: 1920,
|
|
56
|
+
* video: {
|
|
57
|
+
* codec: 'h264',
|
|
58
|
+
* preset: 'medium',
|
|
59
|
+
* crf: 23,
|
|
60
|
+
* },
|
|
61
|
+
* audio: {
|
|
62
|
+
* codec: 'aac',
|
|
63
|
+
* bitrate: '128k',
|
|
64
|
+
* },
|
|
65
|
+
* });
|
|
66
|
+
* ```
|
|
67
|
+
*
|
|
68
|
+
* @packageDocumentation
|
|
69
|
+
*/
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Audio codec options
|
|
73
|
+
*/
|
|
74
|
+
export declare interface AudioCodecOptions {
|
|
75
|
+
/**
|
|
76
|
+
* Audio codec to use
|
|
77
|
+
*/
|
|
78
|
+
codec: 'aac' | 'mp3' | 'opus' | 'vorbis';
|
|
79
|
+
/**
|
|
80
|
+
* Bitrate (e.g., '128k', '192k')
|
|
81
|
+
* @default '128k'
|
|
82
|
+
*/
|
|
83
|
+
bitrate?: string;
|
|
84
|
+
/**
|
|
85
|
+
* Sample rate
|
|
86
|
+
* @default 44100
|
|
87
|
+
*/
|
|
88
|
+
sampleRate?: number;
|
|
89
|
+
/**
|
|
90
|
+
* Number of channels
|
|
91
|
+
* @default 2
|
|
92
|
+
*/
|
|
93
|
+
channels?: number;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Options for audio mixing
|
|
98
|
+
*/
|
|
99
|
+
export declare interface AudioMixOptions {
|
|
100
|
+
/**
|
|
101
|
+
* Replace existing audio or mix with it
|
|
102
|
+
* @default 'replace'
|
|
103
|
+
*/
|
|
104
|
+
mode?: 'replace' | 'mix';
|
|
105
|
+
/**
|
|
106
|
+
* Volume of original audio (0-1, only for 'mix' mode)
|
|
107
|
+
* @default 0.5
|
|
108
|
+
*/
|
|
109
|
+
originalVolume?: number;
|
|
110
|
+
/**
|
|
111
|
+
* Volume of new audio (0-1)
|
|
112
|
+
* @default 1
|
|
113
|
+
*/
|
|
114
|
+
newVolume?: number;
|
|
115
|
+
/**
|
|
116
|
+
* Start time for audio in video (seconds)
|
|
117
|
+
* @default 0
|
|
118
|
+
*/
|
|
119
|
+
startTime?: number;
|
|
120
|
+
/**
|
|
121
|
+
* Fade in duration (seconds)
|
|
122
|
+
*/
|
|
123
|
+
fadeIn?: number;
|
|
124
|
+
/**
|
|
125
|
+
* Fade out duration (seconds)
|
|
126
|
+
*/
|
|
127
|
+
fadeOut?: number;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Options for video composition
|
|
132
|
+
*/
|
|
133
|
+
export declare interface ComposeOptions {
|
|
134
|
+
/**
|
|
135
|
+
* Base video buffer or path
|
|
136
|
+
*/
|
|
137
|
+
baseVideo: Buffer | string;
|
|
138
|
+
/**
|
|
139
|
+
* Audio track to add/replace (optional)
|
|
140
|
+
*/
|
|
141
|
+
audio?: Buffer | string;
|
|
142
|
+
/**
|
|
143
|
+
* Overlays to add to the video
|
|
144
|
+
*/
|
|
145
|
+
overlays?: OverlayConfig[];
|
|
146
|
+
/**
|
|
147
|
+
* Output format
|
|
148
|
+
* @default 'mp4'
|
|
149
|
+
*/
|
|
150
|
+
outputFormat?: VideoFormat;
|
|
151
|
+
/**
|
|
152
|
+
* Output quality (1-51 for h264, lower is better)
|
|
153
|
+
* @default 23
|
|
154
|
+
*/
|
|
155
|
+
quality?: number;
|
|
156
|
+
/**
|
|
157
|
+
* Output width (optional, maintains aspect ratio if only width specified)
|
|
158
|
+
*/
|
|
159
|
+
width?: number;
|
|
160
|
+
/**
|
|
161
|
+
* Output height (optional, maintains aspect ratio if only height specified)
|
|
162
|
+
*/
|
|
163
|
+
height?: number;
|
|
164
|
+
/**
|
|
165
|
+
* Output fps (optional, uses source fps if not specified)
|
|
166
|
+
*/
|
|
167
|
+
fps?: number;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
export declare const defaultMediaBundleHandlers: MediaBundleHandler[];
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* Options for extracting frames
|
|
174
|
+
*/
|
|
175
|
+
export declare interface ExtractFrameOptions {
|
|
176
|
+
/**
|
|
177
|
+
* Output format for frame
|
|
178
|
+
* @default 'png'
|
|
179
|
+
*/
|
|
180
|
+
format?: 'png' | 'jpg' | 'webp';
|
|
181
|
+
/**
|
|
182
|
+
* Output width (optional)
|
|
183
|
+
*/
|
|
184
|
+
width?: number;
|
|
185
|
+
/**
|
|
186
|
+
* Output height (optional)
|
|
187
|
+
*/
|
|
188
|
+
height?: number;
|
|
189
|
+
/**
|
|
190
|
+
* JPEG/WebP quality (1-100)
|
|
191
|
+
* @default 90
|
|
192
|
+
*/
|
|
193
|
+
quality?: number;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* FFmpeg-based video processor
|
|
198
|
+
*
|
|
199
|
+
* @example
|
|
200
|
+
* ```typescript
|
|
201
|
+
* import { FFmpegProcessor } from '@happyvertical/video';
|
|
202
|
+
*
|
|
203
|
+
* const processor = new FFmpegProcessor();
|
|
204
|
+
*
|
|
205
|
+
* // Get video metadata
|
|
206
|
+
* const metadata = await processor.getMetadata('input.mp4');
|
|
207
|
+
* console.log(`Duration: ${metadata.duration}s`);
|
|
208
|
+
*
|
|
209
|
+
* // Extract thumbnail
|
|
210
|
+
* const thumbnail = await processor.extractFrame('input.mp4', 2.0, {
|
|
211
|
+
* format: 'jpg',
|
|
212
|
+
* width: 1280,
|
|
213
|
+
* });
|
|
214
|
+
*
|
|
215
|
+
* // Add lower-third overlay
|
|
216
|
+
* const output = await processor.addLowerThird('input.mp4', {
|
|
217
|
+
* title: 'John Smith',
|
|
218
|
+
* subtitle: 'News Anchor',
|
|
219
|
+
* style: 'news',
|
|
220
|
+
* duration: 5,
|
|
221
|
+
* });
|
|
222
|
+
* ```
|
|
223
|
+
*/
|
|
224
|
+
export declare class FFmpegProcessor implements VideoProcessor {
|
|
225
|
+
private options;
|
|
226
|
+
private logger;
|
|
227
|
+
constructor(options?: VideoProcessorOptions);
|
|
228
|
+
/**
|
|
229
|
+
* Create a temporary directory for processing
|
|
230
|
+
*/
|
|
231
|
+
private createTempDir;
|
|
232
|
+
/**
|
|
233
|
+
* Save buffer to a temporary file
|
|
234
|
+
*/
|
|
235
|
+
private saveToTemp;
|
|
236
|
+
/**
|
|
237
|
+
* Get input path (save buffer to temp if needed)
|
|
238
|
+
*/
|
|
239
|
+
private getInputPath;
|
|
240
|
+
/**
|
|
241
|
+
* Run FFmpeg command
|
|
242
|
+
* Uses execFile with array arguments to prevent command injection
|
|
243
|
+
*/
|
|
244
|
+
private runFFmpeg;
|
|
245
|
+
/**
|
|
246
|
+
* Run FFprobe command and parse JSON output
|
|
247
|
+
* Uses execFile with array arguments to prevent command injection
|
|
248
|
+
*/
|
|
249
|
+
private runFFprobe;
|
|
250
|
+
/**
|
|
251
|
+
* Get video metadata
|
|
252
|
+
*/
|
|
253
|
+
getMetadata(video: Buffer | string): Promise<VideoMetadata>;
|
|
254
|
+
/**
|
|
255
|
+
* Extract a single frame from video
|
|
256
|
+
*/
|
|
257
|
+
extractFrame(video: Buffer | string, timestamp: number, options?: ExtractFrameOptions): Promise<Buffer>;
|
|
258
|
+
/**
|
|
259
|
+
* Transcode video to different format/codec
|
|
260
|
+
*/
|
|
261
|
+
transcode(video: Buffer | string, options: TranscodeOptions): Promise<Buffer>;
|
|
262
|
+
/**
|
|
263
|
+
* Get FFmpeg args for video codec options
|
|
264
|
+
*/
|
|
265
|
+
private getVideoCodecArgs;
|
|
266
|
+
/**
|
|
267
|
+
* Add an overlay to video
|
|
268
|
+
*/
|
|
269
|
+
addOverlay(video: Buffer | string, overlay: OverlayConfig): Promise<Buffer>;
|
|
270
|
+
/**
|
|
271
|
+
* Add a lower-third overlay
|
|
272
|
+
*/
|
|
273
|
+
addLowerThird(video: Buffer | string, config: LowerThirdConfig): Promise<Buffer>;
|
|
274
|
+
/**
|
|
275
|
+
* Compose video with overlays and audio
|
|
276
|
+
*/
|
|
277
|
+
compose(options: ComposeOptions): Promise<Buffer>;
|
|
278
|
+
/**
|
|
279
|
+
* Concatenate multiple videos
|
|
280
|
+
*/
|
|
281
|
+
concatenate(videos: Array<Buffer | string>): Promise<Buffer>;
|
|
282
|
+
/**
|
|
283
|
+
* Mix audio into video
|
|
284
|
+
*/
|
|
285
|
+
mixAudio(video: Buffer | string, audio: Buffer | string, options?: AudioMixOptions): Promise<Buffer>;
|
|
286
|
+
/**
|
|
287
|
+
* Convert animated WEBP to MP4
|
|
288
|
+
*
|
|
289
|
+
* Uses sharp to extract frames from animated WEBP (which ffmpeg can't decode
|
|
290
|
+
* natively), then assembles them into an MP4 using ffmpeg.
|
|
291
|
+
*/
|
|
292
|
+
convertWebpToMp4(webp: Buffer, options?: WebpConvertOptions): Promise<Buffer>;
|
|
293
|
+
/**
|
|
294
|
+
* Get overlay position as FFmpeg expression
|
|
295
|
+
*/
|
|
296
|
+
private getOverlayPosition;
|
|
297
|
+
/**
|
|
298
|
+
* Get FFmpeg enable expression for time-based visibility
|
|
299
|
+
*/
|
|
300
|
+
private getEnableExpression;
|
|
301
|
+
/**
|
|
302
|
+
* Escape text for FFmpeg drawtext filter
|
|
303
|
+
*/
|
|
304
|
+
private escapeFFmpegText;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
export declare const genericImageBundleHandler: MediaBundleHandler;
|
|
308
|
+
|
|
309
|
+
export declare const genericVideoBundleHandler: MediaBundleHandler;
|
|
310
|
+
|
|
311
|
+
export declare function inspectMediaBundle(files: MediaFileDescriptor[], options?: InspectMediaBundleOptions): Promise<MediaBundleInspection>;
|
|
312
|
+
|
|
313
|
+
export declare interface InspectMediaBundleOptions extends MediaBundleInspectContext {
|
|
314
|
+
handlers?: MediaBundleHandler[];
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
export declare const insta360BundleHandler: MediaBundleHandler;
|
|
318
|
+
|
|
319
|
+
export declare interface Insta360FileIdentity {
|
|
320
|
+
prefix: 'VID' | 'LRV';
|
|
321
|
+
date: string;
|
|
322
|
+
time: string;
|
|
323
|
+
streamIndex: string;
|
|
324
|
+
sequence: string;
|
|
325
|
+
extension: string;
|
|
326
|
+
bundleKey: string;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* Lower-third overlay template
|
|
331
|
+
*/
|
|
332
|
+
export declare interface LowerThirdConfig {
|
|
333
|
+
/**
|
|
334
|
+
* Primary text (e.g., person's name)
|
|
335
|
+
*/
|
|
336
|
+
title: string;
|
|
337
|
+
/**
|
|
338
|
+
* Secondary text (e.g., job title)
|
|
339
|
+
*/
|
|
340
|
+
subtitle?: string;
|
|
341
|
+
/**
|
|
342
|
+
* Template style
|
|
343
|
+
*/
|
|
344
|
+
style: 'minimal' | 'news' | 'corporate' | 'gradient';
|
|
345
|
+
/**
|
|
346
|
+
* Primary color
|
|
347
|
+
* @default '#1a1a1a'
|
|
348
|
+
*/
|
|
349
|
+
primaryColor?: string;
|
|
350
|
+
/**
|
|
351
|
+
* Accent color
|
|
352
|
+
* @default '#0066cc'
|
|
353
|
+
*/
|
|
354
|
+
accentColor?: string;
|
|
355
|
+
/**
|
|
356
|
+
* Duration to display in seconds
|
|
357
|
+
*/
|
|
358
|
+
duration?: number;
|
|
359
|
+
/**
|
|
360
|
+
* Start time in seconds
|
|
361
|
+
* @default 0
|
|
362
|
+
*/
|
|
363
|
+
startTime?: number;
|
|
364
|
+
/**
|
|
365
|
+
* Logo image (optional)
|
|
366
|
+
*/
|
|
367
|
+
logo?: Buffer | string;
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
export declare type MediaBundleCapability = 'gps-track' | 'image-metadata' | 'sidecar-binding' | 'stitch-export' | 'stream-info' | (string & {});
|
|
371
|
+
|
|
372
|
+
export declare type MediaBundleFileRole = 'primary' | 'support' | 'metadata' | 'unknown';
|
|
373
|
+
|
|
374
|
+
export declare interface MediaBundleHandler {
|
|
375
|
+
id: string;
|
|
376
|
+
version: string;
|
|
377
|
+
priority: number;
|
|
378
|
+
capabilities?: MediaBundleCapability[];
|
|
379
|
+
supports(files: MediaFileDescriptor[], context: MediaBundleInspectContext): boolean | Promise<boolean>;
|
|
380
|
+
inspect(files: MediaFileDescriptor[], context: MediaBundleInspectContext): Promise<MediaBundleInspection>;
|
|
381
|
+
validate?(inspection: MediaBundleInspection, context: MediaBundleInspectContext): Promise<string[]> | string[];
|
|
382
|
+
deriveArtifacts?(inspection: MediaBundleInspection, context: MediaBundleInspectContext): Promise<unknown[]> | unknown[];
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
export declare interface MediaBundleInspectContext {
|
|
386
|
+
tools?: MediaBundleInspectTools;
|
|
387
|
+
probe?: boolean;
|
|
388
|
+
defaultSupportFileVisibility?: MediaSupportFileVisibility;
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
export declare interface MediaBundleInspection {
|
|
392
|
+
handlerId: string;
|
|
393
|
+
handlerVersion: string;
|
|
394
|
+
formatFamily: MediaFormatFamily;
|
|
395
|
+
primary: MediaFileDescriptor;
|
|
396
|
+
supportFiles: MediaBundleSupportFile[];
|
|
397
|
+
metadata: NormalizedMediaMetadata;
|
|
398
|
+
capabilities: MediaBundleCapability[];
|
|
399
|
+
warnings: string[];
|
|
400
|
+
errors: string[];
|
|
401
|
+
raw?: Record<string, unknown>;
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
export declare interface MediaBundleInspectTools {
|
|
405
|
+
ffprobePath?: string;
|
|
406
|
+
exiftoolPath?: string;
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
export declare interface MediaBundleSupportFile {
|
|
410
|
+
file: MediaFileDescriptor;
|
|
411
|
+
role: MediaBundleFileRole;
|
|
412
|
+
relationship: string;
|
|
413
|
+
visibility: MediaSupportFileVisibility;
|
|
414
|
+
metadata?: NormalizedMediaMetadata;
|
|
415
|
+
}
|
|
416
|
+
|
|
417
|
+
export declare interface MediaFileDescriptor {
|
|
418
|
+
path: string;
|
|
419
|
+
relativePath?: string;
|
|
420
|
+
name?: string;
|
|
421
|
+
mimeType?: string;
|
|
422
|
+
sizeBytes?: number;
|
|
423
|
+
sha256?: string;
|
|
424
|
+
modifiedAt?: Date | string;
|
|
425
|
+
role?: MediaBundleFileRole;
|
|
426
|
+
metadata?: Record<string, unknown>;
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
export declare type MediaFormatFamily = 'generic-image' | 'generic-video' | 'insta360' | 'unknown';
|
|
430
|
+
|
|
431
|
+
export declare type MediaSupportFileVisibility = 'visible' | 'hidden-retained' | 'drop-after-extract';
|
|
432
|
+
|
|
433
|
+
export declare interface NormalizedGpsTrackPoint {
|
|
434
|
+
tSeconds: number;
|
|
435
|
+
recordedAt?: Date | string | null;
|
|
436
|
+
latitude: number;
|
|
437
|
+
longitude: number;
|
|
438
|
+
altitude?: number | null;
|
|
439
|
+
heading?: number | null;
|
|
440
|
+
speedMps?: number | null;
|
|
441
|
+
sourceFilePath?: string;
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
export declare interface NormalizedMediaDevice {
|
|
445
|
+
make?: string;
|
|
446
|
+
model?: string;
|
|
447
|
+
serialNumber?: string;
|
|
448
|
+
firmwareVersion?: string;
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
export declare interface NormalizedMediaMetadata {
|
|
452
|
+
captureTime?: Date | string | null;
|
|
453
|
+
device?: NormalizedMediaDevice;
|
|
454
|
+
width?: number;
|
|
455
|
+
height?: number;
|
|
456
|
+
durationMs?: number;
|
|
457
|
+
mimeType?: string;
|
|
458
|
+
streams?: NormalizedMediaStream[];
|
|
459
|
+
gpsTrack?: NormalizedGpsTrackPoint[];
|
|
460
|
+
raw?: Record<string, unknown>;
|
|
461
|
+
private?: Record<string, unknown>;
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
export declare interface NormalizedMediaStream {
|
|
465
|
+
kind: 'video' | 'audio' | 'data' | 'unknown';
|
|
466
|
+
codec?: string;
|
|
467
|
+
width?: number;
|
|
468
|
+
height?: number;
|
|
469
|
+
fps?: number;
|
|
470
|
+
durationMs?: number;
|
|
471
|
+
bitrate?: number;
|
|
472
|
+
metadata?: Record<string, unknown>;
|
|
473
|
+
}
|
|
474
|
+
|
|
475
|
+
/**
|
|
476
|
+
* Configuration for a video overlay
|
|
477
|
+
*/
|
|
478
|
+
export declare interface OverlayConfig {
|
|
479
|
+
/**
|
|
480
|
+
* Type of overlay
|
|
481
|
+
*/
|
|
482
|
+
type: 'image' | 'text' | 'video';
|
|
483
|
+
/**
|
|
484
|
+
* Content for the overlay
|
|
485
|
+
* - For 'image': Buffer or path to image file
|
|
486
|
+
* - For 'text': The text string to display
|
|
487
|
+
* - For 'video': Buffer or path to video file
|
|
488
|
+
*/
|
|
489
|
+
content: Buffer | string;
|
|
490
|
+
/**
|
|
491
|
+
* Position of the overlay
|
|
492
|
+
*/
|
|
493
|
+
position: OverlayPosition;
|
|
494
|
+
/**
|
|
495
|
+
* Start time in seconds (0 = from beginning)
|
|
496
|
+
* @default 0
|
|
497
|
+
*/
|
|
498
|
+
startTime?: number;
|
|
499
|
+
/**
|
|
500
|
+
* End time in seconds (undefined = until end)
|
|
501
|
+
*/
|
|
502
|
+
endTime?: number;
|
|
503
|
+
/**
|
|
504
|
+
* Opacity (0-1)
|
|
505
|
+
* @default 1
|
|
506
|
+
*/
|
|
507
|
+
opacity?: number;
|
|
508
|
+
/**
|
|
509
|
+
* Width of overlay (optional)
|
|
510
|
+
*/
|
|
511
|
+
width?: number;
|
|
512
|
+
/**
|
|
513
|
+
* Height of overlay (optional)
|
|
514
|
+
*/
|
|
515
|
+
height?: number;
|
|
516
|
+
/**
|
|
517
|
+
* Text-specific options
|
|
518
|
+
*/
|
|
519
|
+
textOptions?: TextOverlayOptions;
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
/**
|
|
523
|
+
* Position configuration for overlays
|
|
524
|
+
*/
|
|
525
|
+
export declare interface OverlayPosition {
|
|
526
|
+
/**
|
|
527
|
+
* Horizontal position
|
|
528
|
+
* - number: pixels from left
|
|
529
|
+
* - 'left' | 'center' | 'right': alignment
|
|
530
|
+
*/
|
|
531
|
+
x: number | 'left' | 'center' | 'right';
|
|
532
|
+
/**
|
|
533
|
+
* Vertical position
|
|
534
|
+
* - number: pixels from top
|
|
535
|
+
* - 'top' | 'center' | 'bottom': alignment
|
|
536
|
+
*/
|
|
537
|
+
y: number | 'top' | 'center' | 'bottom';
|
|
538
|
+
/**
|
|
539
|
+
* Padding from edges (used with alignment keywords)
|
|
540
|
+
* @default 20
|
|
541
|
+
*/
|
|
542
|
+
padding?: number;
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
export declare function parseInsta360FileName(file: MediaFileDescriptor): Insta360FileIdentity | null;
|
|
546
|
+
|
|
547
|
+
/**
|
|
548
|
+
* Options for text overlays
|
|
549
|
+
*/
|
|
550
|
+
export declare interface TextOverlayOptions {
|
|
551
|
+
/**
|
|
552
|
+
* Font family
|
|
553
|
+
* @default 'Arial'
|
|
554
|
+
*/
|
|
555
|
+
fontFamily?: string;
|
|
556
|
+
/**
|
|
557
|
+
* Font size in pixels
|
|
558
|
+
* @default 24
|
|
559
|
+
*/
|
|
560
|
+
fontSize?: number;
|
|
561
|
+
/**
|
|
562
|
+
* Font color (hex or named color)
|
|
563
|
+
* @default 'white'
|
|
564
|
+
*/
|
|
565
|
+
fontColor?: string;
|
|
566
|
+
/**
|
|
567
|
+
* Background color (hex or named color, with alpha)
|
|
568
|
+
*/
|
|
569
|
+
backgroundColor?: string;
|
|
570
|
+
/**
|
|
571
|
+
* Padding around text in pixels
|
|
572
|
+
* @default 10
|
|
573
|
+
*/
|
|
574
|
+
padding?: number;
|
|
575
|
+
/**
|
|
576
|
+
* Border radius in pixels (for background)
|
|
577
|
+
* @default 0
|
|
578
|
+
*/
|
|
579
|
+
borderRadius?: number;
|
|
580
|
+
/**
|
|
581
|
+
* Text alignment
|
|
582
|
+
* @default 'left'
|
|
583
|
+
*/
|
|
584
|
+
alignment?: 'left' | 'center' | 'right';
|
|
585
|
+
/**
|
|
586
|
+
* Maximum width before wrapping
|
|
587
|
+
*/
|
|
588
|
+
maxWidth?: number;
|
|
589
|
+
/**
|
|
590
|
+
* Animation type for text entry
|
|
591
|
+
*/
|
|
592
|
+
animation?: 'none' | 'fade' | 'slide-left' | 'slide-up';
|
|
593
|
+
/**
|
|
594
|
+
* Animation duration in seconds
|
|
595
|
+
* @default 0.5
|
|
596
|
+
*/
|
|
597
|
+
animationDuration?: number;
|
|
598
|
+
}
|
|
599
|
+
|
|
600
|
+
/**
|
|
601
|
+
* Options for video transcoding
|
|
602
|
+
*/
|
|
603
|
+
export declare interface TranscodeOptions {
|
|
604
|
+
/**
|
|
605
|
+
* Output format
|
|
606
|
+
*/
|
|
607
|
+
format: VideoFormat;
|
|
608
|
+
/**
|
|
609
|
+
* Video codec options
|
|
610
|
+
*/
|
|
611
|
+
video?: VideoCodecOptions;
|
|
612
|
+
/**
|
|
613
|
+
* Audio codec options
|
|
614
|
+
*/
|
|
615
|
+
audio?: AudioCodecOptions;
|
|
616
|
+
/**
|
|
617
|
+
* Output width (optional)
|
|
618
|
+
*/
|
|
619
|
+
width?: number;
|
|
620
|
+
/**
|
|
621
|
+
* Output height (optional)
|
|
622
|
+
*/
|
|
623
|
+
height?: number;
|
|
624
|
+
/**
|
|
625
|
+
* Output fps (optional)
|
|
626
|
+
*/
|
|
627
|
+
fps?: number;
|
|
628
|
+
/**
|
|
629
|
+
* Start time for trimming (seconds)
|
|
630
|
+
*/
|
|
631
|
+
startTime?: number;
|
|
632
|
+
/**
|
|
633
|
+
* End time for trimming (seconds)
|
|
634
|
+
*/
|
|
635
|
+
endTime?: number;
|
|
636
|
+
}
|
|
637
|
+
|
|
638
|
+
/**
|
|
639
|
+
* Video codec options
|
|
640
|
+
*/
|
|
641
|
+
export declare interface VideoCodecOptions {
|
|
642
|
+
/**
|
|
643
|
+
* Video codec to use
|
|
644
|
+
*/
|
|
645
|
+
codec: 'h264' | 'h265' | 'vp9' | 'av1';
|
|
646
|
+
/**
|
|
647
|
+
* Encoding preset (faster = lower quality)
|
|
648
|
+
*/
|
|
649
|
+
preset?: 'ultrafast' | 'superfast' | 'veryfast' | 'faster' | 'fast' | 'medium' | 'slow' | 'slower' | 'veryslow';
|
|
650
|
+
/**
|
|
651
|
+
* CRF value (0-51 for h264/h265, 0-63 for vp9)
|
|
652
|
+
*/
|
|
653
|
+
crf?: number;
|
|
654
|
+
/**
|
|
655
|
+
* Bitrate target (e.g., '2M', '5000k')
|
|
656
|
+
*/
|
|
657
|
+
bitrate?: string;
|
|
658
|
+
/**
|
|
659
|
+
* Pixel format
|
|
660
|
+
* @default 'yuv420p'
|
|
661
|
+
*/
|
|
662
|
+
pixelFormat?: string;
|
|
663
|
+
}
|
|
664
|
+
|
|
665
|
+
/**
|
|
666
|
+
* Supported video output formats
|
|
667
|
+
*/
|
|
668
|
+
export declare type VideoFormat = 'mp4' | 'webm' | 'mov' | 'avi' | 'mkv';
|
|
669
|
+
|
|
670
|
+
/**
|
|
671
|
+
* Video metadata extracted from a file
|
|
672
|
+
*/
|
|
673
|
+
export declare interface VideoMetadata {
|
|
674
|
+
/**
|
|
675
|
+
* Duration in seconds
|
|
676
|
+
*/
|
|
677
|
+
duration: number;
|
|
678
|
+
/**
|
|
679
|
+
* Width in pixels
|
|
680
|
+
*/
|
|
681
|
+
width: number;
|
|
682
|
+
/**
|
|
683
|
+
* Height in pixels
|
|
684
|
+
*/
|
|
685
|
+
height: number;
|
|
686
|
+
/**
|
|
687
|
+
* Frames per second
|
|
688
|
+
*/
|
|
689
|
+
fps: number;
|
|
690
|
+
/**
|
|
691
|
+
* Video codec (e.g., 'h264', 'vp9')
|
|
692
|
+
*/
|
|
693
|
+
codec: string;
|
|
694
|
+
/**
|
|
695
|
+
* Bitrate in bits per second
|
|
696
|
+
*/
|
|
697
|
+
bitrate?: number;
|
|
698
|
+
/**
|
|
699
|
+
* Aspect ratio as string (e.g., '16:9')
|
|
700
|
+
*/
|
|
701
|
+
aspectRatio: string;
|
|
702
|
+
/**
|
|
703
|
+
* Audio streams present
|
|
704
|
+
*/
|
|
705
|
+
hasAudio: boolean;
|
|
706
|
+
/**
|
|
707
|
+
* Audio codec if present
|
|
708
|
+
*/
|
|
709
|
+
audioCodec?: string;
|
|
710
|
+
/**
|
|
711
|
+
* Audio sample rate if present
|
|
712
|
+
*/
|
|
713
|
+
audioSampleRate?: number;
|
|
714
|
+
/**
|
|
715
|
+
* File size in bytes
|
|
716
|
+
*/
|
|
717
|
+
fileSize?: number;
|
|
718
|
+
/**
|
|
719
|
+
* Container format (e.g., 'mp4', 'webm')
|
|
720
|
+
*/
|
|
721
|
+
format: string;
|
|
722
|
+
}
|
|
723
|
+
|
|
724
|
+
/**
|
|
725
|
+
* Video processor interface
|
|
726
|
+
*/
|
|
727
|
+
export declare interface VideoProcessor {
|
|
728
|
+
/**
|
|
729
|
+
* Compose a video with overlays and audio
|
|
730
|
+
*/
|
|
731
|
+
compose(options: ComposeOptions): Promise<Buffer>;
|
|
732
|
+
/**
|
|
733
|
+
* Extract a single frame from a video
|
|
734
|
+
*/
|
|
735
|
+
extractFrame(video: Buffer | string, timestamp: number, options?: ExtractFrameOptions): Promise<Buffer>;
|
|
736
|
+
/**
|
|
737
|
+
* Add overlays to a video
|
|
738
|
+
*/
|
|
739
|
+
addOverlay(video: Buffer | string, overlay: OverlayConfig): Promise<Buffer>;
|
|
740
|
+
/**
|
|
741
|
+
* Add a lower-third overlay
|
|
742
|
+
*/
|
|
743
|
+
addLowerThird(video: Buffer | string, config: LowerThirdConfig): Promise<Buffer>;
|
|
744
|
+
/**
|
|
745
|
+
* Get video metadata
|
|
746
|
+
*/
|
|
747
|
+
getMetadata(video: Buffer | string): Promise<VideoMetadata>;
|
|
748
|
+
/**
|
|
749
|
+
* Transcode video to different format/codec
|
|
750
|
+
*/
|
|
751
|
+
transcode(video: Buffer | string, options: TranscodeOptions): Promise<Buffer>;
|
|
752
|
+
/**
|
|
753
|
+
* Concatenate multiple videos
|
|
754
|
+
*/
|
|
755
|
+
concatenate(videos: Array<Buffer | string>): Promise<Buffer>;
|
|
756
|
+
/**
|
|
757
|
+
* Mix audio into video
|
|
758
|
+
*/
|
|
759
|
+
mixAudio(video: Buffer | string, audio: Buffer | string, options?: AudioMixOptions): Promise<Buffer>;
|
|
760
|
+
/**
|
|
761
|
+
* Convert animated WEBP to MP4
|
|
762
|
+
*
|
|
763
|
+
* Uses sharp to extract frames from animated WEBP (which ffmpeg can't decode),
|
|
764
|
+
* then assembles them into an MP4 using ffmpeg.
|
|
765
|
+
*/
|
|
766
|
+
convertWebpToMp4?(webp: Buffer, options?: WebpConvertOptions): Promise<Buffer>;
|
|
767
|
+
}
|
|
768
|
+
|
|
769
|
+
/**
|
|
770
|
+
* Video Processing Types
|
|
771
|
+
*
|
|
772
|
+
* Types for video composition, transcoding, and manipulation.
|
|
773
|
+
*/
|
|
774
|
+
/**
|
|
775
|
+
* Configuration for the video processor
|
|
776
|
+
*/
|
|
777
|
+
export declare interface VideoProcessorOptions {
|
|
778
|
+
/**
|
|
779
|
+
* Path to FFmpeg binary
|
|
780
|
+
* @default 'ffmpeg' (expects ffmpeg in PATH)
|
|
781
|
+
*/
|
|
782
|
+
ffmpegPath?: string;
|
|
783
|
+
/**
|
|
784
|
+
* Path to FFprobe binary
|
|
785
|
+
* @default 'ffprobe' (expects ffprobe in PATH)
|
|
786
|
+
*/
|
|
787
|
+
ffprobePath?: string;
|
|
788
|
+
/**
|
|
789
|
+
* Temporary directory for intermediate files
|
|
790
|
+
* @default system temp directory
|
|
791
|
+
*/
|
|
792
|
+
tempDir?: string;
|
|
793
|
+
/**
|
|
794
|
+
* Default timeout for operations in milliseconds
|
|
795
|
+
* @default 300000 (5 minutes)
|
|
796
|
+
*/
|
|
797
|
+
timeout?: number;
|
|
798
|
+
}
|
|
799
|
+
|
|
800
|
+
/**
|
|
801
|
+
* Options for converting animated WEBP to MP4
|
|
802
|
+
*/
|
|
803
|
+
export declare interface WebpConvertOptions {
|
|
804
|
+
/**
|
|
805
|
+
* Frame rate of the output MP4
|
|
806
|
+
* @default 16
|
|
807
|
+
*/
|
|
808
|
+
fps?: number;
|
|
809
|
+
/**
|
|
810
|
+
* Video codec options for the output
|
|
811
|
+
*/
|
|
812
|
+
video?: VideoCodecOptions;
|
|
813
|
+
}
|
|
814
|
+
|
|
815
|
+
export { }
|