From 2259c442c6674cb6a284acf2e56b90f5eb0d42cd Mon Sep 17 00:00:00 2001 From: Jerome Wu Date: Tue, 3 Nov 2020 15:39:56 +0800 Subject: [PATCH] Update docs --- docs/api.md | 219 +++++++++------------------------------------------- 1 file changed, 38 insertions(+), 181 deletions(-) diff --git a/docs/api.md b/docs/api.md index 07fbc5a..2a41bd1 100644 --- a/docs/api.md +++ b/docs/api.md @@ -2,15 +2,8 @@ - [createFFmpeg()](#create-ffmpeg) - [ffmpeg.load](#ffmpeg-load) - - [ffmpeg.write](#ffmpeg-write) - - [ffmpeg.writeText](#ffmpeg-writeText) - - [ffmpeg.read](#ffmpeg-read) - - [ffmpeg.remove](#ffmpeg-remove) - - [ffmpeg.ls](#ffmpeg-ls) - - [ffmpeg.transcode](#ffmpeg-transcode) - - [ffmpeg.trim](#ffmpeg-trim) - - [ffmpeg.concatDemuxer](#ffmpeg-concatDemuxer) - [ffmpeg.run](#ffmpeg-run) + - [ffmpeg.FS](#ffmpeg-fs) --- @@ -33,7 +26,7 @@ createFFmpeg is a factory function that creates a ffmpeg instance. ```javascript const { createFFmpeg } = FFmpeg; const ffmpeg = createFFmpeg({ - corePath: "./node_modules/@ffmpeg/core/ffmpeg-core.js", + corePath: "./node_modules/@ffmpeg/core/dist/ffmpeg-core.js", log: true, }); ``` @@ -42,7 +35,11 @@ const ffmpeg = createFFmpeg({ ### ffmpeg.load(): Promise -ffmpeg.load() loads ffmpeg-core.js script (download from remote if not presented), it makes WebAssembly code ready to use. +Load ffmpeg.wasm-core script. + +In browser environment, the ffmpeg.wasm-core script is fetch from CDN and can be assign to a local path by assigning `corePath`. In node environment, we use dynamic require and the default `corePath` is `$ffmpeg/core`. + +Typically the load() func might take few seconds to minutes to complete, better to do it as early as possible. **Examples:** @@ -52,187 +49,47 @@ ffmpeg.load() loads ffmpeg-core.js script (download from remote if not presented })(); ``` - - -### ffmpeg.write(path, data): Promise - -ffmpeg.write() writes data to specific path in Emscripten file system, it is an essential step before doing any other tasks. - -> Currently we found an issue that you should not have parallel Worker.write() as it may cause unexpected behavior, please do it in sequential for-loop like [HERE](https://github.com/ffmpegjs/ffmpeg.js/blob/master/examples/browser/image2video.html#L36) - -**Arguments:** - -- `path` path to write data to file system -- `data` data to write, can be Uint8Array, URL, File, Blob or base64 format - -**Examples:** - -```javascript -(async () => { - await ffmpeg.write( - "flame.avi", - "http://localhost:3000/tests/assets/flame.avi" - ); -})(); -``` - - - -### ffmpeg.writeText(path, text): undefined - -ffmpeg.write() writes text data to specific path in Emscripten file system. - -**Arguments:** - -- `path` path to write data to file system -- `text` string to write to file - -**Examples:** - -```javascript -(async () => { - ffmpeg.writeText("sub.srt", "..."); -})(); -``` - - - -### ffmpeg.read(path): Uint8Array - -ffmpeg.read() reads data from file system, often used to get output data after specific task. - -**Arguments:** - -- `path` path to read data from file system - -**Examples:** - -```javascript -(async () => { - const data = ffmpeg.read("output.mp4"); -})(); -``` - - - -### ffmpeg.remove(path): Promise - -ffmpeg.remove() removes files in file system, it will be better to delete unused files if you need to run ffmpeg.js multiple times. - -**Arguments:** - -- `path` path for file to delete - -**Examples:** - -```javascript -(async () => { - ffmpeg.remove("output.mp4"); -})(); -``` - - - -### ffmpeg.ls(path): Promise - -ffmpeg.ls() lists all files in specific path. - -**Arguments:** - -- `path` path to list - -**Examples:** - -```javascript -(async () => { - const dirs = ffmpeg.ls("/"); -})(); -``` - - - -### ffmpeg.transcode(input, output, options): Promise - -ffmpeg.transcode() transcode a video file to another format. - -**Arguments:** - -- `input` input file path, the input file should be written through ffmpeg.write() -- `output` output file path, can be read with ffmpeg.read() later -- `options` a string to add extra arguments to ffmpeg - -**Examples:** - -```javascript -(async () => { - await ffmpeg.transcode("flame.avi", "output.mp4", "-s 1920x1080"); -})(); -``` - - - -### ffmpeg.trim(input, output, from, to, options): Promise - -ffmpeg.trim() trims video to specific interval. - -**Arguments:** - -- `inputPath` input file path, the input file should be written through ffmpeg.write() -- `outputPath` output file path, can be read with ffmpeg.read() later -- `from` start time, can be in time stamp (00:00:12.000) or seconds (12) -- `to` end time, rule same as above -- `options` a string to add extra arguments to ffmpeg - -**Examples:** - -```javascript -(async () => { - await ffmpeg.trim("flame.avi", "output.mp4", 1, 2); -})(); -``` - - - -### ffmpeg.concatDemuxer(input, output, options): Promise - -ffmpeg.concatDemuxer() concatenates multiple videos using concatDemuxer. This method won't encode the videos again. But it has its limitations. See [Concat demuxer Wiki](https://trac.ffmpeg.org/wiki/Concatenate) - -**Arguments:** - -- `input` input file paths as an Array, the input files should be written through ffmpeg.write() -- `output` output file path, can be read with ffmpeg.read() later -- `options` a string to add extra arguments to ffmpeg - -**Examples:** - -```javascript -(async () => { - await ffmpeg.concatDemuxer(["flame-1.avi", "flame-2.avi"], "output.mp4"); -})(); -``` - -If the input video files are the same as the output video file, you can pass an extra option to speed up the process - -```javascript -(async () => { - await ffmpeg.concatDemuxer(["flame-1.mp4", "flame-2.mp4"], "output.mp4", "-c copy"); -})(); -``` - -### ffmpeg.run(args): Promise +### ffmpeg.run(...args): Promise -ffmpeg.run() is similar to FFmpeg cli tool, aims to provide maximum flexiblity for users. +This is the major function in ffmpeg.wasm, you can just imagine it as ffmpeg native cli and what you need to pass is the same. **Arguments:** -- `args` a string to represent arguments +- `args` string arguments just like cli tool. **Examples:** ```javascript (async () => { - await ffmpeg.run("-i flame.avi -s 1920x1080 output.mp4"); + await ffmpeg.run('-i', 'flame.avi', '-s', '1920x1080', 'output.mp4'); + /* equals to `$ ffmpeg -i flame.avi -s 1920x1080 output.mp4` */ })(); ``` + + + +### ffmpeg.FS(method, ...args): any + +Run FS operations. + +For input/output file of ffmpeg.wasm, it is required to save them to MEMFS first so that ffmpeg.wasm is able to consume them. Here we rely on the FS methods provided by Emscripten. + +For more info, check https://emscripten.org/docs/api_reference/Filesystem-API.html + +**Arguments:** + +- `method` string method name +- `args` arguments to pass to method + +**Examples:** + +```javascript +/* Write data to MEMFS, need to use Uint8Array for binary data */ +ffmpeg.FS('writeFile', 'video.avi', new Uint8Array(...)); +/* Read data from MEMFS */ +ffmpeg.FS('readFile', 'video.mp4'); +/* Delete file in MEMFS */ +ffmpeg.FS('unlink', 'video.mp4'); +```