Skip to content

Commit 5ad350d

Browse files
jeromewujeromewu
committed
Update docs
1 parent 3790103 commit 5ad350d

File tree

1 file changed

+25
-168
lines changed

1 file changed

+25
-168
lines changed

‎docs/api.md

Lines changed: 25 additions & 168 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,8 @@
22

33
- [createFFmpeg()](#create-ffmpeg)
44
- [ffmpeg.load](#ffmpeg-load)
5-
- [ffmpeg.write](#ffmpeg-write)
6-
- [ffmpeg.writeText](#ffmpeg-writeText)
7-
- [ffmpeg.read](#ffmpeg-read)
8-
- [ffmpeg.remove](#ffmpeg-remove)
9-
- [ffmpeg.ls](#ffmpeg-ls)
10-
- [ffmpeg.transcode](#ffmpeg-transcode)
11-
- [ffmpeg.trim](#ffmpeg-trim)
12-
- [ffmpeg.concatDemuxer](#ffmpeg-concatDemuxer)
135
- [ffmpeg.run](#ffmpeg-run)
6+
- [ffmpeg.FS](#ffmpeg-fs)
147

158
---
169

@@ -33,7 +26,7 @@ createFFmpeg is a factory function that creates a ffmpeg instance.
3326
```javascript
3427
const { createFFmpeg } = FFmpeg;
3528
const ffmpeg = createFFmpeg({
36-
corePath: "./node_modules/@ffmpeg/core/ffmpeg-core.js",
29+
corePath: "./node_modules/@ffmpeg/core/dist/ffmpeg-core.js",
3730
log: true,
3831
});
3932
```
@@ -42,197 +35,61 @@ const ffmpeg = createFFmpeg({
4235

4336
### ffmpeg.load(): Promise
4437

45-
ffmpeg.load() loads ffmpeg-core.js script (download from remote if not presented), it makes WebAssembly code ready to use.
38+
Load ffmpeg.wasm-core script.
4639

47-
**Examples:**
48-
49-
```javascript
50-
(async () => {
51-
await ffmpeg.load();
52-
})();
53-
```
54-
55-
<a name="ffmpeg-write"></a>
56-
57-
### ffmpeg.write(path, data): Promise
58-
59-
ffmpeg.write() writes data to specific path in Emscripten file system, it is an essential step before doing any other tasks.
60-
61-
> 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)
62-
63-
**Arguments:**
64-
65-
- `path` path to write data to file system
66-
- `data` data to write, can be Uint8Array, URL, File, Blob or base64 format
67-
68-
**Examples:**
69-
70-
```javascript
71-
(async () => {
72-
await ffmpeg.write(
73-
"flame.avi",
74-
"http://localhost:3000/tests/assets/flame.avi"
75-
);
76-
})();
77-
```
78-
79-
<a name="ffmpeg-writeText"></a>
80-
81-
### ffmpeg.writeText(path, text): undefined
82-
83-
ffmpeg.write() writes text data to specific path in Emscripten file system.
84-
85-
**Arguments:**
86-
87-
- `path` path to write data to file system
88-
- `text` string to write to file
89-
90-
**Examples:**
91-
92-
```javascript
93-
(async () => {
94-
ffmpeg.writeText("sub.srt", "...");
95-
})();
96-
```
97-
98-
<a name="ffmpeg-read"></a>
99-
100-
### ffmpeg.read(path): Uint8Array
101-
102-
ffmpeg.read() reads data from file system, often used to get output data after specific task.
103-
104-
**Arguments:**
105-
106-
- `path` path to read data from file system
107-
108-
**Examples:**
109-
110-
```javascript
111-
(async () => {
112-
const data = ffmpeg.read("output.mp4");
113-
})();
114-
```
115-
116-
<a name="ffmpeg-remove"></a>
117-
118-
### ffmpeg.remove(path): Promise
119-
120-
ffmpeg.remove() removes files in file system, it will be better to delete unused files if you need to run ffmpeg.js multiple times.
40+
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`.
12141

122-
**Arguments:**
123-
124-
- `path` path for file to delete
125-
126-
**Examples:**
127-
128-
```javascript
129-
(async () => {
130-
ffmpeg.remove("output.mp4");
131-
})();
132-
```
133-
134-
<a name="ffmpeg-ls"></a>
135-
136-
### ffmpeg.ls(path): Promise
137-
138-
ffmpeg.ls() lists all files in specific path.
139-
140-
**Arguments:**
141-
142-
- `path` path to list
143-
144-
**Examples:**
145-
146-
```javascript
147-
(async () => {
148-
const dirs = ffmpeg.ls("/");
149-
})();
150-
```
151-
152-
<a name="ffmpeg-transcode"></a>
153-
154-
### ffmpeg.transcode(input, output, options): Promise
155-
156-
ffmpeg.transcode() transcode a video file to another format.
157-
158-
**Arguments:**
159-
160-
- `input` input file path, the input file should be written through ffmpeg.write()
161-
- `output` output file path, can be read with ffmpeg.read() later
162-
- `options` a string to add extra arguments to ffmpeg
42+
Typically the load() func might take few seconds to minutes to complete, better to do it as early as possible.
16343

16444
**Examples:**
16545

16646
```javascript
16747
(async () => {
168-
await ffmpeg.transcode("flame.avi", "output.mp4", "-s 1920x1080");
169-
})();
170-
```
171-
172-
<a name="ffmpeg-trim"></a>
173-
174-
### ffmpeg.trim(input, output, from, to, options): Promise
175-
176-
ffmpeg.trim() trims video to specific interval.
177-
178-
**Arguments:**
179-
180-
- `inputPath` input file path, the input file should be written through ffmpeg.write()
181-
- `outputPath` output file path, can be read with ffmpeg.read() later
182-
- `from` start time, can be in time stamp (00:00:12.000) or seconds (12)
183-
- `to` end time, rule same as above
184-
- `options` a string to add extra arguments to ffmpeg
185-
186-
**Examples:**
187-
188-
```javascript
189-
(async () => {
190-
await ffmpeg.trim("flame.avi", "output.mp4", 1, 2);
48+
await ffmpeg.load();
19149
})();
19250
```
19351

194-
<a name="ffmpeg-concatDemuxer"></a>
52+
<a name="ffmpeg-run"></a>
19553

196-
### ffmpeg.concatDemuxer(input, output, options): Promise
54+
### ffmpeg.run(...args): Promise
19755

198-
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)
56+
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.
19957

20058
**Arguments:**
20159

202-
- `input` input file paths as an Array, the input files should be written through ffmpeg.write()
203-
- `output` output file path, can be read with ffmpeg.read() later
204-
- `options` a string to add extra arguments to ffmpeg
60+
- `args` string arguments just like cli tool.
20561

20662
**Examples:**
20763

20864
```javascript
20965
(async () => {
210-
await ffmpeg.concatDemuxer(["flame-1.avi", "flame-2.avi"], "output.mp4");
66+
await ffmpeg.run('-i', 'flame.avi', '-s', '1920x1080', 'output.mp4');
67+
/* equals to `$ ffmpeg -i flame.avi -s 1920x1080 output.mp4` */
21168
})();
21269
```
21370

214-
If the input video files are the same as the output video file, you can pass an extra option to speed up the process
71+
<a name="ffmpeg-fs"></a>
21572

216-
```javascript
217-
(async () => {
218-
await ffmpeg.concatDemuxer(["flame-1.mp4", "flame-2.mp4"], "output.mp4", "-c copy");
219-
})();
220-
```
73+
### ffmpeg.FS(method, ...args): any
22174

222-
<a name="ffmpeg-run"></a>
75+
Run FS operations.
22376

224-
### ffmpeg.run(args): Promise
77+
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.
22578

226-
ffmpeg.run() is similar to FFmpeg cli tool, aims to provide maximum flexiblity for users.
79+
For more info, check https://emscripten.org/docs/api_reference/Filesystem-API.html
22780

22881
**Arguments:**
22982

230-
- `args` a string to represent arguments
83+
- `method` string method name
84+
- `args` arguments to pass to method
23185

23286
**Examples:**
23387

23488
```javascript
235-
(async () => {
236-
await ffmpeg.run("-i flame.avi -s 1920x1080 output.mp4");
237-
})();
89+
/* Write data to MEMFS, need to use Uint8Array for binary data */
90+
ffmpeg.FS('writeFile', 'video.avi', new Uint8Array(...));
91+
/* Read data from MEMFS */
92+
ffmpeg.FS('readFile', 'video.mp4');
93+
/* Delete file in MEMFS */
94+
ffmpeg.FS('unlink', 'video.mp4');
23895
```

0 commit comments

Comments
 (0)