# 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)
```typescript
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
```typescript
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
```