From c3af3dba90250db0f11716642ce5600dbf098226 Mon Sep 17 00:00:00 2001 From: Nadi Co Date: Thu, 17 Mar 2022 20:53:16 +0200 Subject: [PATCH 1/2] clearer instruction on how to use --- README.md | 115 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 68 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index cf28cfe..9795301 100644 --- a/README.md +++ b/README.md @@ -7,19 +7,21 @@ This library provides FFmpeg builds ported to JavaScript using [Emscripten proje ## Builds Currently available builds (additional builds may be added in future): -* `ffmpeg-webm.js` - WebM encoding (VP8 & Opus encoders, popular decoders). -* `ffmpeg-worker-webm.js` - Web Worker version of `ffmpeg-webm.js`. -* `ffmpeg-mp4.js` - MP4 encoding (H.264 & AAC & MP3 encoders, popular decoders). -* `ffmpeg-worker-mp4.js` - Web Worker version of `ffmpeg-mp4.js`. + +- `ffmpeg-webm.js` - WebM encoding (VP8 & Opus encoders, popular decoders). +- `ffmpeg-worker-webm.js` - Web Worker version of `ffmpeg-webm.js`. +- `ffmpeg-mp4.js` - MP4 encoding (H.264 & AAC & MP3 encoders, popular decoders). +- `ffmpeg-worker-mp4.js` - Web Worker version of `ffmpeg-mp4.js`. Note: only NPM releases contain abovementioned files. ## Version scheme ffmpeg.js uses the following version pattern: `major.minor.9ddd`, where: -* **major** - FFmpeg's major version number used in the builds. -* **minor** - FFmpeg's minor version. -* **ddd** - ffmpeg.js own patch version. Should not be confused with FFmpeg's patch version number. + +- **major** - FFmpeg's major version number used in the builds. +- **minor** - FFmpeg's minor version. +- **ddd** - ffmpeg.js own patch version. Should not be confused with FFmpeg's patch version number. Example: `2.7.9005` @@ -38,9 +40,13 @@ let stderr = ""; // Print FFmpeg's version. ffmpeg({ arguments: ["-version"], - print: function(data) { stdout += data + "\n"; }, - printErr: function(data) { stderr += data + "\n"; }, - onExit: function(code) { + print: function (data) { + stdout += data + "\n"; + }, + printErr: function (data) { + stderr += data + "\n"; + }, + onExit: function (code) { console.log("Process exited with code " + code); console.log(stdout); console.log(stderr); @@ -53,35 +59,37 @@ Use e.g. [browserify](https://github.com/browserify/browserify) in case of Brows ### Via Web Worker ffmpeg.js also provides wrapper for main function with Web Worker interface to offload the work to a different process. Worker sends the following messages: -* `{type: "ready"}` - Worker loaded and ready to accept commands. -* `{type: "run"}` - Worker started the job. -* `{type: "stdout", data: ""}` - FFmpeg printed to stdout. -* `{type: "stderr", data: ""}` - FFmpeg printed to stderr. -* `{type: "exit", data: ""}` - FFmpeg exited. -* `{type: "done", data: ""}` - Job finished with some result. -* `{type: "error", data: ""}` - Error occurred. -* `{type: "abort", data: ""}` - FFmpeg terminated abnormally (e.g. out of memory, wasm error). + +- `{type: "ready"}` - Worker loaded and ready to accept commands. +- `{type: "run"}` - Worker started the job. +- `{type: "stdout", data: ""}` - FFmpeg printed to stdout. +- `{type: "stderr", data: ""}` - FFmpeg printed to stderr. +- `{type: "exit", data: ""}` - FFmpeg exited. +- `{type: "done", data: ""}` - Job finished with some result. +- `{type: "error", data: ""}` - Error occurred. +- `{type: "abort", data: ""}` - FFmpeg terminated abnormally (e.g. out of memory, wasm error). You can send the following messages to the worker: -* `{type: "run", ...opts}` - Start new job with provided options. + +- `{type: "run", ...opts}` - Start new job with provided options. ```js const worker = new Worker("ffmpeg-worker-webm.js"); -worker.onmessage = function(e) { +worker.onmessage = function (e) { const msg = e.data; switch (msg.type) { - case "ready": - worker.postMessage({type: "run", arguments: ["-version"]}); - break; - case "stdout": - console.log(msg.data); - break; - case "stderr": - console.log(msg.data); - break; - case "done": - console.log(msg.data); - break; + case "ready": + worker.postMessage({ type: "run", arguments: ["-version"] }); + break; + case "stdout": + console.log(msg.data); + break; + case "stderr": + console.log(msg.data); + break; + case "done": + console.log(msg.data); + break; } }; ``` @@ -90,9 +98,10 @@ You can use [worker_threads](https://nodejs.org/api/worker_threads.html) module ### Files -Empscripten supports several types of [file systems](https://emscripten.org/docs/api_reference/Filesystem-API.html#file-systems). ffmpeg.js uses [MEMFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#memfs) to store the input/output files in FFmpeg's working directory. You need to pass *Array* of *Object* to `MEMFS` option with the following keys: -* **name** *(String)* - File name, can't contain slashes. -* **data** *(ArrayBuffer/ArrayBufferView/Array)* - File data. +Empscripten supports several types of [file systems](https://emscripten.org/docs/api_reference/Filesystem-API.html#file-systems). ffmpeg.js uses [MEMFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#memfs) to store the input/output files in FFmpeg's working directory. You need to pass _Array_ of _Object_ to `MEMFS` option with the following keys: + +- **name** _(String)_ - File name, can't contain slashes. +- **data** _(ArrayBuffer/ArrayBufferView/Array)_ - File data. ffmpeg.js resulting object has `MEMFS` option with the same structure and contains files which weren't passed to the input, i.e. new files created by FFmpeg. @@ -102,7 +111,7 @@ const fs = require("fs"); const testData = new Uint8Array(fs.readFileSync("test.webm")); // Encode test video to VP8. const result = ffmpeg({ - MEMFS: [{name: "test.webm", data: testData}], + MEMFS: [{ name: "test.webm", data: testData }], arguments: ["-i", "test.webm", "-c:v", "libvpx", "-an", "out.webm"], }); // Write out.webm to disk. @@ -110,10 +119,11 @@ const out = result.MEMFS[0]; fs.writeFileSync(out.name, Buffer(out.data)); ``` -You can also mount other FS by passing *Array* of *Object* to `mounts` option with the following keys: -* **type** *(String)* - Name of the file system. -* **opts** *(Object)* - Underlying file system options. -* **mountpoint** *(String)* - Mount path, must start with a slash, must not contain other slashes and also the following paths are blacklisted: `/tmp`, `/home`, `/dev`, `/work`. Mount directory will be created automatically before mount. +You can also mount other FS by passing _Array_ of _Object_ to `mounts` option with the following keys: + +- **type** _(String)_ - Name of the file system. +- **opts** _(Object)_ - Underlying file system options. +- **mountpoint** _(String)_ - Mount path, must start with a slash, must not contain other slashes and also the following paths are blacklisted: `/tmp`, `/home`, `/dev`, `/work`. Mount directory will be created automatically before mount. See documentation of [FS.mount](https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.mount) for more details. @@ -121,8 +131,16 @@ See documentation of [FS.mount](https://emscripten.org/docs/api_reference/Filesy const ffmpeg = require("ffmpeg.js"); ffmpeg({ // Mount /data inside application to the current directory. - mounts: [{type: "NODEFS", opts: {root: "."}, mountpoint: "/data"}], - arguments: ["-i", "/data/test.webm", "-c:v", "libvpx", "-an", "-y", "/data/out.webm"], + mounts: [{ type: "NODEFS", opts: { root: "." }, mountpoint: "/data" }], + arguments: [ + "-i", + "/data/test.webm", + "-c:v", + "libvpx", + "-an", + "-y", + "/data/out.webm", + ], }); // out.webm was written to the current directory. ``` @@ -132,6 +150,7 @@ ffmpeg({ It's recommended to use [Docker](https://www.docker.com/) to build ffmpeg.js. 1. Clone ffmpeg.js repository with submodules: + ```bash git clone https://github.com/Kagami/ffmpeg.js.git --recurse-submodules ``` @@ -140,7 +159,7 @@ It's recommended to use [Docker](https://www.docker.com/) to build ffmpeg.js. 3. Build everything: ```bash - docker run --rm -it -v /path/to/ffmpeg.js:/mnt -w /opt kagamihi/ffmpeg.js + docker run --rm -it -v /absolute/path/to/ffmpeg.js:/mnt -w /opt kagamihi/ffmpeg.js # cp -a /mnt/{.git,build,Makefile} . && source /root/emsdk/emsdk_env.sh && make && cp ffmpeg*.js /mnt ``` @@ -178,8 +197,9 @@ Own library code licensed under LGPL 2.1 or later. This build uses LGPL version of FFmpeg and thus available under LGPL 2.1 or later. See [here](https://www.ffmpeg.org/legal.html) for more details and FFmpeg's license information. Included libraries: -* libopus [licensed under BSD](https://git.xiph.org/?p=opus.git;a=blob;f=COPYING). -* libvpx [licensed under BSD](https://chromium.googlesource.com/webm/libvpx/+/master/LICENSE). + +- libopus [licensed under BSD](https://git.xiph.org/?p=opus.git;a=blob;f=COPYING). +- libvpx [licensed under BSD](https://chromium.googlesource.com/webm/libvpx/+/master/LICENSE). See [LICENSE.WEBM](https://github.com/Kagami/ffmpeg.js/blob/master/LICENSE.WEBM) for the full text of software licenses used in this build. @@ -188,7 +208,8 @@ See [LICENSE.WEBM](https://github.com/Kagami/ffmpeg.js/blob/master/LICENSE.WEBM) This build uses GPL version of FFmpeg and thus available under GPL 2.0. It also includes patent encumbered H.264, AAC and MP3 encoders. Make sure to contact lawyer before using it in your country. Included libraries: -* x264 [licensed under GPL](https://git.videolan.org/?p=x264.git;a=blob;f=COPYING). -* LAME [licensed under LGPL](https://github.com/rbrito/lame/blob/origin/COPYING). + +- x264 [licensed under GPL](https://git.videolan.org/?p=x264.git;a=blob;f=COPYING). +- LAME [licensed under LGPL](https://github.com/rbrito/lame/blob/origin/COPYING). See [LICENSE.MP4](https://github.com/Kagami/ffmpeg.js/blob/master/LICENSE.MP4) for the full text of software licenses used in this build. From 7753356bd2f03df4f262a79299a18afffd453ae5 Mon Sep 17 00:00:00 2001 From: Nadi Co Date: Thu, 17 Mar 2022 21:10:48 +0200 Subject: [PATCH 2/2] clearer instruction on how to use --- README.md | 113 ++++++++++++++++++++++-------------------------------- 1 file changed, 46 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 9795301..95e1ac6 100644 --- a/README.md +++ b/README.md @@ -7,21 +7,19 @@ This library provides FFmpeg builds ported to JavaScript using [Emscripten proje ## Builds Currently available builds (additional builds may be added in future): - -- `ffmpeg-webm.js` - WebM encoding (VP8 & Opus encoders, popular decoders). -- `ffmpeg-worker-webm.js` - Web Worker version of `ffmpeg-webm.js`. -- `ffmpeg-mp4.js` - MP4 encoding (H.264 & AAC & MP3 encoders, popular decoders). -- `ffmpeg-worker-mp4.js` - Web Worker version of `ffmpeg-mp4.js`. +* `ffmpeg-webm.js` - WebM encoding (VP8 & Opus encoders, popular decoders). +* `ffmpeg-worker-webm.js` - Web Worker version of `ffmpeg-webm.js`. +* `ffmpeg-mp4.js` - MP4 encoding (H.264 & AAC & MP3 encoders, popular decoders). +* `ffmpeg-worker-mp4.js` - Web Worker version of `ffmpeg-mp4.js`. Note: only NPM releases contain abovementioned files. ## Version scheme ffmpeg.js uses the following version pattern: `major.minor.9ddd`, where: - -- **major** - FFmpeg's major version number used in the builds. -- **minor** - FFmpeg's minor version. -- **ddd** - ffmpeg.js own patch version. Should not be confused with FFmpeg's patch version number. +* **major** - FFmpeg's major version number used in the builds. +* **minor** - FFmpeg's minor version. +* **ddd** - ffmpeg.js own patch version. Should not be confused with FFmpeg's patch version number. Example: `2.7.9005` @@ -40,13 +38,9 @@ let stderr = ""; // Print FFmpeg's version. ffmpeg({ arguments: ["-version"], - print: function (data) { - stdout += data + "\n"; - }, - printErr: function (data) { - stderr += data + "\n"; - }, - onExit: function (code) { + print: function(data) { stdout += data + "\n"; }, + printErr: function(data) { stderr += data + "\n"; }, + onExit: function(code) { console.log("Process exited with code " + code); console.log(stdout); console.log(stderr); @@ -59,37 +53,35 @@ Use e.g. [browserify](https://github.com/browserify/browserify) in case of Brows ### Via Web Worker ffmpeg.js also provides wrapper for main function with Web Worker interface to offload the work to a different process. Worker sends the following messages: - -- `{type: "ready"}` - Worker loaded and ready to accept commands. -- `{type: "run"}` - Worker started the job. -- `{type: "stdout", data: ""}` - FFmpeg printed to stdout. -- `{type: "stderr", data: ""}` - FFmpeg printed to stderr. -- `{type: "exit", data: ""}` - FFmpeg exited. -- `{type: "done", data: ""}` - Job finished with some result. -- `{type: "error", data: ""}` - Error occurred. -- `{type: "abort", data: ""}` - FFmpeg terminated abnormally (e.g. out of memory, wasm error). +* `{type: "ready"}` - Worker loaded and ready to accept commands. +* `{type: "run"}` - Worker started the job. +* `{type: "stdout", data: ""}` - FFmpeg printed to stdout. +* `{type: "stderr", data: ""}` - FFmpeg printed to stderr. +* `{type: "exit", data: ""}` - FFmpeg exited. +* `{type: "done", data: ""}` - Job finished with some result. +* `{type: "error", data: ""}` - Error occurred. +* `{type: "abort", data: ""}` - FFmpeg terminated abnormally (e.g. out of memory, wasm error). You can send the following messages to the worker: - -- `{type: "run", ...opts}` - Start new job with provided options. +* `{type: "run", ...opts}` - Start new job with provided options. ```js const worker = new Worker("ffmpeg-worker-webm.js"); -worker.onmessage = function (e) { +worker.onmessage = function(e) { const msg = e.data; switch (msg.type) { - case "ready": - worker.postMessage({ type: "run", arguments: ["-version"] }); - break; - case "stdout": - console.log(msg.data); - break; - case "stderr": - console.log(msg.data); - break; - case "done": - console.log(msg.data); - break; + case "ready": + worker.postMessage({type: "run", arguments: ["-version"]}); + break; + case "stdout": + console.log(msg.data); + break; + case "stderr": + console.log(msg.data); + break; + case "done": + console.log(msg.data); + break; } }; ``` @@ -98,10 +90,9 @@ You can use [worker_threads](https://nodejs.org/api/worker_threads.html) module ### Files -Empscripten supports several types of [file systems](https://emscripten.org/docs/api_reference/Filesystem-API.html#file-systems). ffmpeg.js uses [MEMFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#memfs) to store the input/output files in FFmpeg's working directory. You need to pass _Array_ of _Object_ to `MEMFS` option with the following keys: - -- **name** _(String)_ - File name, can't contain slashes. -- **data** _(ArrayBuffer/ArrayBufferView/Array)_ - File data. +Empscripten supports several types of [file systems](https://emscripten.org/docs/api_reference/Filesystem-API.html#file-systems). ffmpeg.js uses [MEMFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#memfs) to store the input/output files in FFmpeg's working directory. You need to pass *Array* of *Object* to `MEMFS` option with the following keys: +* **name** *(String)* - File name, can't contain slashes. +* **data** *(ArrayBuffer/ArrayBufferView/Array)* - File data. ffmpeg.js resulting object has `MEMFS` option with the same structure and contains files which weren't passed to the input, i.e. new files created by FFmpeg. @@ -111,7 +102,7 @@ const fs = require("fs"); const testData = new Uint8Array(fs.readFileSync("test.webm")); // Encode test video to VP8. const result = ffmpeg({ - MEMFS: [{ name: "test.webm", data: testData }], + MEMFS: [{name: "test.webm", data: testData}], arguments: ["-i", "test.webm", "-c:v", "libvpx", "-an", "out.webm"], }); // Write out.webm to disk. @@ -119,11 +110,10 @@ const out = result.MEMFS[0]; fs.writeFileSync(out.name, Buffer(out.data)); ``` -You can also mount other FS by passing _Array_ of _Object_ to `mounts` option with the following keys: - -- **type** _(String)_ - Name of the file system. -- **opts** _(Object)_ - Underlying file system options. -- **mountpoint** _(String)_ - Mount path, must start with a slash, must not contain other slashes and also the following paths are blacklisted: `/tmp`, `/home`, `/dev`, `/work`. Mount directory will be created automatically before mount. +You can also mount other FS by passing *Array* of *Object* to `mounts` option with the following keys: +* **type** *(String)* - Name of the file system. +* **opts** *(Object)* - Underlying file system options. +* **mountpoint** *(String)* - Mount path, must start with a slash, must not contain other slashes and also the following paths are blacklisted: `/tmp`, `/home`, `/dev`, `/work`. Mount directory will be created automatically before mount. See documentation of [FS.mount](https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.mount) for more details. @@ -131,16 +121,8 @@ See documentation of [FS.mount](https://emscripten.org/docs/api_reference/Filesy const ffmpeg = require("ffmpeg.js"); ffmpeg({ // Mount /data inside application to the current directory. - mounts: [{ type: "NODEFS", opts: { root: "." }, mountpoint: "/data" }], - arguments: [ - "-i", - "/data/test.webm", - "-c:v", - "libvpx", - "-an", - "-y", - "/data/out.webm", - ], + mounts: [{type: "NODEFS", opts: {root: "."}, mountpoint: "/data"}], + arguments: ["-i", "/data/test.webm", "-c:v", "libvpx", "-an", "-y", "/data/out.webm"], }); // out.webm was written to the current directory. ``` @@ -150,7 +132,6 @@ ffmpeg({ It's recommended to use [Docker](https://www.docker.com/) to build ffmpeg.js. 1. Clone ffmpeg.js repository with submodules: - ```bash git clone https://github.com/Kagami/ffmpeg.js.git --recurse-submodules ``` @@ -197,9 +178,8 @@ Own library code licensed under LGPL 2.1 or later. This build uses LGPL version of FFmpeg and thus available under LGPL 2.1 or later. See [here](https://www.ffmpeg.org/legal.html) for more details and FFmpeg's license information. Included libraries: - -- libopus [licensed under BSD](https://git.xiph.org/?p=opus.git;a=blob;f=COPYING). -- libvpx [licensed under BSD](https://chromium.googlesource.com/webm/libvpx/+/master/LICENSE). +* libopus [licensed under BSD](https://git.xiph.org/?p=opus.git;a=blob;f=COPYING). +* libvpx [licensed under BSD](https://chromium.googlesource.com/webm/libvpx/+/master/LICENSE). See [LICENSE.WEBM](https://github.com/Kagami/ffmpeg.js/blob/master/LICENSE.WEBM) for the full text of software licenses used in this build. @@ -208,8 +188,7 @@ See [LICENSE.WEBM](https://github.com/Kagami/ffmpeg.js/blob/master/LICENSE.WEBM) This build uses GPL version of FFmpeg and thus available under GPL 2.0. It also includes patent encumbered H.264, AAC and MP3 encoders. Make sure to contact lawyer before using it in your country. Included libraries: - -- x264 [licensed under GPL](https://git.videolan.org/?p=x264.git;a=blob;f=COPYING). -- LAME [licensed under LGPL](https://github.com/rbrito/lame/blob/origin/COPYING). +* x264 [licensed under GPL](https://git.videolan.org/?p=x264.git;a=blob;f=COPYING). +* LAME [licensed under LGPL](https://github.com/rbrito/lame/blob/origin/COPYING). See [LICENSE.MP4](https://github.com/Kagami/ffmpeg.js/blob/master/LICENSE.MP4) for the full text of software licenses used in this build.