initial

readme.hints.md

@@ -0,0 +1,70 @@
+# 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
+```