smartffmpeg/readme.hints.md

Implementation Notes

Architecture

• Main class: SmartFfmpeg in ts/classes.smartffmpeg.ts
• Builder class: FfmpegCommand in ts/classes.ffmpegcommand.ts
• Entry point: ts/index.ts
• Uses ffmpeg-static and ffprobe-static for bundled binaries
• Direct child_process spawning via createRequire for CommonJS compatibility

Key Design Decisions

1. Modern Builder API: Fluent chainable API similar to modern JS libraries (e.g., Knex, Prisma)

2. Web Streams API: Uses Web Streams (ReadableStream/WritableStream) for cross-platform compatibility

   • Input: string | Buffer | Uint8Array | ReadableStream<Uint8Array>
   • Output: toStream() returns ReadableStream<Uint8Array>
   • Piping: pipe() accepts WritableStream<Uint8Array>
   • Internally converts between Web Streams and Node streams using Readable.toWeb()/Readable.fromWeb()

3. No fluent-ffmpeg: The deprecated fluent-ffmpeg library was avoided in favor of direct ffmpeg invocation

4. Backward Compatibility: Legacy API methods are preserved alongside the new builder API

5. Static binaries: Uses ffmpeg-static and ffprobe-static for cross-platform binary distribution

API Patterns

Builder API (Recommended)

const result = await ffmpeg.input(source)
  .videoCodec('libx264')
  .output('output.mp4')
  .run();

// Web Streams
const webStream: ReadableStream<Uint8Array> = ffmpeg.input(buffer, { format: 'mp4' })
  .videoCodec('libx264')
  .toStream('webm');

Legacy API

await ffmpeg.convert('input.mp4', 'output.mp4', { videoCodec: 'libx264' });

Dependencies

• ffmpeg-static: Provides ffmpeg binary
• ffprobe-static: Provides ffprobe binary for media analysis
• @push.rocks/smartfs: Filesystem operations
• @push.rocks/smartpath: Path utilities
• @push.rocks/smartpromise: Promise utilities

Development

• Run tests: pnpm test
• Build: pnpm build

File Structure

ts/
├── 00_commitinfo_data.ts  # Package metadata
├── plugins.ts             # Centralized imports
├── interfaces.ts          # TypeScript types
├── classes.smartffmpeg.ts # Main SmartFfmpeg class
├── classes.ffmpegcommand.ts # Builder command class
└── index.ts               # Public exports