dumtruck/konowebcodecs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documents

Browse Source
This commit is contained in:
Jerome Wu
2020-04-28 19:36:33 +08:00
parent b36360f16f
commit 55cbf63fb1
14 changed files with 202 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
docs/api.md
View File

@@ -1,67 +1,61 @@
# API
- [createWorker()](#create-worker)
- [Worker.load](#worker-load)
- [Worker.write](#worker-write)
- [Worker.writeText](#worker-writeText)
- [Worker.read](#worker-read)
- [Worker.remove](#worker-remove)
- [Worker.transcode](#worker-transcode)
- [Worker.trim](#worker-trim)
- [Worker.concatDemuxer](#worker-concatDemuxer)
- [Worker.run](#worker-run)
- [Worker.terminate](#worker-terminate)
- [createFFmpeg()](#create-ffmpeg)
- [ffmpeg.load](#ffmpeg-load)
- [ffmpeg.write](#ffmpeg-write)
- [ffmpeg.writeText](#ffmpeg-writeText)
- [ffmpeg.read](#ffmpeg-read)
- [ffmpeg.remove](#ffmpeg-remove)
- [ffmpeg.transcode](#ffmpeg-transcode)
- [ffmpeg.trim](#ffmpeg-trim)
- [ffmpeg.concatDemuxer](#ffmpeg-concatDemuxer)
- [ffmpeg.run](#ffmpeg-run)
---
<a name="create-worker"></a>
<a name="create-ffmpeg"></a>
## createWorker(options): Worker
## createFFmpeg(options): ffmpeg
createWorker is a factory function that creates a ffmpeg worker, a worker is basically a Web Worker in browser and Child Process in Node.
createFFmpeg is a factory function that creates a ffmpeg instance.
**Arguments:**
- `options` an object of customized options
- `corePath` path for ffmpeg-core.js script
- `workerPath` path for downloading worker script
- `workerBlobURL` a boolean to define whether to use Blob URL for worker script, default: true
- `logger` a function to log the progress, a quick example is `m => console.log(m)`
- `log` a boolean to turn on all logs, default is `false`
- `logger` a function to get log messages, a quick example is `({ message }) => console.log(message)`
- `progress` a function to trace the progress, a quick example is `p => console.log(p)`
**Examples:**
```javascript
const { createWorker } = FFmpeg;
const worker = createWorker({
const { createFFmpeg } = FFmpeg;
const ffmpeg = createFFmpeg({
corePath: "./node_modules/@ffmpeg/core/ffmpeg-core.js",
logger: m => console.log(m)
log: true,
});
```
<a name="worker-load"></a>
<a name="ffmpeg-load"></a>
### Worker.load(jobId): Promise
### ffmpeg.load(): Promise
Worker.load() loads ffmpeg-core.js script (download from remote if not presented), it makes Web Worker/Child Process ready for next action.
**Arguments:**
- `jobId` jobId is generated by ffmpeg.js to identify each job, but you can put your own when calling the function.
ffmpeg.load() loads ffmpeg-core.js script (download from remote if not presented), it makes WebAssembly code ready to use.
**Examples:**
```javascript
(async () => {
await worker.load();
await ffmpeg.load();
})();
```
<a name="worker-write"></a>
<a name="ffmpeg-write"></a>
### Worker.write(path, data, jobId): Promise
### ffmpeg.write(path, data): Promise
Worker.write() writes data to specific path in Emscripten file system, it is an essential step before doing any other tasks.
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)
@@ -69,139 +63,150 @@ Worker.write() writes data to specific path in Emscripten file system, it is an
- `path` path to write data to file system
- `data` data to write, can be Uint8Array, URL or base64 format
- `jobId` @see Worker.load()
**Examples:**
```javascript
(async () => {
await worker.write(
await ffmpeg.write(
"flame.avi",
"http://localhost:3000/tests/assets/flame.avi"
);
})();
```
<a name="worker-writeText"></a>
<a name="ffmpeg-writeText"></a>
### Worker.writeText(path, text, jobId): Promise
### ffmpeg.writeText(path, text): undefined
Worker.write() writes text data to specific path in Emscripten file system.
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
- `jobId` @see Worker.load()
**Examples:**
```javascript
(async () => {
await worker.write("sub.srt", "...");
ffmpeg.writeText("sub.srt", "...");
})();
```
<a name="worker-read"></a>
<a name="ffmpeg-read"></a>
### Worker.read(path, jobId): Promise
### ffmpeg.read(path): Uint8Array
Worker.read() reads data from file system, often used to get output data after specific task.
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
- `jobId` @see Worker.load()
**Examples:**
```javascript
(async () => {
const { data } = await worker.read("output.mp4");
const data = ffmpeg.read("output.mp4");
})();
```
<a name="worker-remove"></a>
<a name="ffmpeg-remove"></a>
### Worker.remove(path, jobId): Promise
### ffmpeg.remove(path): Promise
Worker.remove() removes files in file system, it will be better to delete unused files if you need to run ffmpeg.js multiple times.
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
- `jobId` @see Worker.load()
**Examples:**
```javascript
(async () => {
await worker.remove("output.mp4");
ffmpeg.remove("output.mp4");
})();
```
<a name="worker-transcode"></a>
<a name="ffmpeg-ls"></a>
### Worker.transcode(input, output, options, jobId): Promise
### ffmpeg.ls(path): Promise
Worker.transcode() transcode a video file to another format.
ffmpeg.ls() lists all files in specific path.
**Arguments:**
- `input` input file path, the input file should be written through Worker.write()
- `output` output file path, can be read with Worker.read() later
- `path` path to list
**Examples:**
```javascript
(async () => {
const dirs = ffmpeg.ls("/");
})();
```
<a name="ffmpeg-transcode"></a>
### 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
- `jobId` @see Worker.load()
**Examples:**
```javascript
(async () => {
await worker.transcode("flame.avi", "output.mp4", "-s 1920x1080");
await ffmpeg.transcode("flame.avi", "output.mp4", "-s 1920x1080");
})();
```
<a name="worker-trim"></a>
<a name="ffmpeg-trim"></a>
### Worker.trim(input, output, from, to, options, jobId): Promise
### ffmpeg.trim(input, output, from, to, options): Promise
Worker.trim() trims video to specific interval.
ffmpeg.trim() trims video to specific interval.
**Arguments:**
- `inputPath` input file path, the input file should be written through Worker.write()
- `outputPath` output file path, can be read with Worker.read() later
- `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
- `jobId` @see Worker.load()
**Examples:**
```javascript
(async () => {
await worker.trim("flame.avi", "output.mp4", 1, 2);
await ffmpeg.trim("flame.avi", "output.mp4", 1, 2);
})();
```
<a name="worker-concatDemuxer"></a>
<a name="ffmpeg-concatDemuxer"></a>
### Worker.concatDemuxer(input, output, options, jobId): Promise
### ffmpeg.concatDemuxer(input, output, options): Promise
Worker.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)
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 Worker.write()
- `output` output file path, can be read with Worker.read() later
- `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
- `jobId` check Worker.load()
**Examples:**
```javascript
(async () => {
await worker.concatDemuxer(["flame-1.avi", "flame-2.avi"], "output.mp4");
await ffmpeg.concatDemuxer(["flame-1.avi", "flame-2.avi"], "output.mp4");
})();
```
@@ -209,39 +214,24 @@ If the input video files are the same as the output video file, you can pass an
```javascript
(async () => {
await worker.concatDemuxer(["flame-1.mp4", "flame-2.mp4"], "output.mp4", "-c copy");
await ffmpeg.concatDemuxer(["flame-1.mp4", "flame-2.mp4"], "output.mp4", "-c copy");
})();
```
<a name="worker-run"></a>
<a name="ffmpeg-run"></a>
### Worker.run(args, jobId): Promise
### ffmpeg.run(args): Promise
Worker.run() is similar to FFmpeg cli tool, aims to provide maximum flexiblity for users.
ffmpeg.run() is similar to FFmpeg cli tool, aims to provide maximum flexiblity for users.
**Arguments:**
- `args` a string to represent arguments
- `jobId` check Worker.load()
**Examples:**
```javascript
(async () => {
await worker.run("-i flame.avi -s 1920x1080 output.mp4");
})();
```
<a name="worker-run"></a>
### Worker.terminate(): Promise
Worker.terminate() terminates web worker / worker\_threads, after terminate(), you cannot use this worker anymore.
**Examples:**
```javascript
(async () => {
await worker.terminate();
await ffmpeg.run("-i flame.avi -s 1920x1080 output.mp4");
})();
```