Merge pull request nwjs#4665 from ghostoy/issue-4595

rogerwang · rogerwang · commit dfa4f71411ff · 2016-04-15T13:22:24.000+08:00
Updated docs for building proprietary codecs easier
diff --git a/docs/For Developers/Enable Proprietary Codecs.md b/docs/For Developers/Enable Proprietary Codecs.md
@@ -24,26 +24,85 @@ ogg,matroska,wav
 !!! warning "License and Patent Fee"
     MP3 and H.264 codecs are licensed under the GPL in `ffmpeg` used by NW.js. Make sure your app are released with compatible license of GPL. And you also have to pay patent licensing royalties for using them. Consult a lawyer if you do not understand the licensing constraints and using patented media formats in your application.
 
-In recent versions of Chromium project, ffmpeg DLL was changed to be builtin. And we don't have license to redistribute the codec in question. So developers don't have any ways to get the codec without compiling. To make things easier, we build ffmpeg as a separate Dll. The Dll we distribute will not contain any proprietary codecs in question. Developers can recompile the Dll for themselves, which is much easier than compiling NW. Or they can get Dll from someone else [from the community](https://github.com/nwjs/nw.js/issues/4492). Note that developers can redistribute binaries containing proprietary codecs as long as they have the license. If a developer doesn't have the license, using this tip or moving to other solutions doesn't make him/her eligible to redistribute the codecs.
+!!! warning "Warning"
+    If you do **NOT** have the license or **NOT** pay the patent fee properly, using this tip below or moving to other solutions does **NOT** make you eligible to redistribute the codecs.
 
-In order to use MP3 and H.264, you'll need to compile ffmpeg with patch and corresponding options.
+### Get FFmpeg DLL from Community
 
-**Step 1.** Apply following patch to `third_party/ffmpeg/ffmpeg.gyp` to make `ffmpeg` include the codecs:
+In recent versions of Chromium project, ffmpeg was changed to be builtin. So you can't get ffmpeg dll any more from official Chrome. But you can get DLL [from the community](https://github.com/nwjs/nw.js/issues/4492). Or build FFmpeg yourself by following instructions below.
+
+### Build FFmpeg DLL without Building NW.js
+
+If you are using pre-built NW.js, you can just only rebuild FFmpeg DLL and replace the bundled DLL in pre-built binaries. This will save lots of time in download size (~1G) comparing to building entire NW.js (~20G).
+
+**Step 1.** Download zip package of customized Chromium from GitHub. You can find the corresponding version in https://github.com/nwjs/chromium.src/tags. Extract the zip package into a local folder, such as `~/nw`. The unzipped package will include a sub directory. So the source folder is in `~/nw/<sub-directory-name>`.
+
+**Step 2.** Fetch dependencies
+
+Since you are not building entire NW.js, you have to fetch following dependencies manually.
+
+* `build/linux/*-sysroot`: This is Linux only. Use `build/linux/sysroot_scripts/install-sysroot.py --running-as-hook` to install the dependencies.
+* `tools/gyp`: See `DEPS` file in the source folder for the repo and commit for this folder.
+* `third_party/yasm/sources/patched-yasm`: See `DEPS` file in the source folder for the repo and commit for this folder.
+* `third_party/ffmpeg`: see DEPS for commit and repo
+* `third_party/llvm-build`: Mac and Linux only. Use `tools/clang/scripts/update.py --if-needed` to download.
+
+**Step 3.** Generate build targets with GYP
+
+!!! tip "For Linux Developers"
+    Please run `build/install-build-deps.sh` for the first time building FFmpeg DLL or NW.js before proceeding to the instructions below. You only have to run it once. This script will install the build dependencies automatically for you.
+
+!!! tip "For Windows Developers"
+    Please include `clang=0` in `GYP_DEFINES` below because Clang build is not enabled on Windows.
+
+```bash
+cd path/to/nw/source/folder
+export GYP_GENERATORS=ninja
+export GYP_DEFINES="branding=Chrome ffmpeg_component=shared_library"
+export PYTHONPATH="$PWD/build"
+./tools/gyp/gyp -I build/common.gypi --depth=. ./third_party/ffmpeg/ffmpeg.gyp
+```
+
+**Step 4.** Build ffmpeg DLL
+
+```bash
+ninja -C out/Release ffmpeg
+```
+
+You will find the DLL in `out/Release` folder. The path and file name varies between platforms:
+
+* Windows: `ffmpeg.dll`
+* Mac OS X: `libffmpeg.dylib`
+* Linux: `lib/libffmpeg.so`
+
+**Step 5.** Replace the bundled DLL in prebuild NW.js with the one you just built. The path and file name varies between platforms:
+
+* Windows: `ffmpeg.dll`
+* Mac OS X: `nwjs.app/Contents/Versions/<chromium-version>/nwjs Framework.framework/libffmpeg.dylib`
+* Linux `lib/libffmpeg.so`
+
+### Build Entire NW.js with Proprietary Codecs
+
+If you don't use official pre-built NW.js, you can build entire NW.js with proprietary codecs enabled by following the instructions below.
+
+**Step 1.** Install prerequists and fetch the source code of NW.js. See *Prerequisits* and *Get the Code* sections in [Building NW.js](Building NW.js.md).
+
+**Step 2.** Apply following patch to `third_party/ffmpeg/ffmpeg.gyp` to make `ffmpeg` include the codecs:
 ```diff
 diff --git a/ffmpeg.gyp b/ffmpeg.gyp                   
 index 294dd2e..7dfcd3a 100755                          
---- a/ffmpeg.gyp                                       
-+++ b/ffmpeg.gyp                                       
-@@ -72,7 +72,7 @@                                      
-       ['chromeos == 1', {                             
-         'ffmpeg_branding%': '<(branding)OS',          
-       }, {  # otherwise, assume Chrome/Chromium.      
--        'ffmpeg_branding%': '<(branding)',            
-+        'ffmpeg_branding%': 'Chrome'                  
-       }],                                             
-     ],                                                
+--- a/ffmpeg.gyp
++++ b/ffmpeg.gyp
+@@ -72,7 +72,7 @@ 
+       ['chromeos == 1', {
+         'ffmpeg_branding%': '<(branding)OS',
+       }, {  # otherwise, assume Chrome/Chromium.
+-        'ffmpeg_branding%': '<(branding)',
++        'ffmpeg_branding%': 'Chrome'
+       }],
+     ],
 ```
 
-**Step 2.** Regenerate the gyp files again with `gclient runhooks`.
+**Step 3.** Regenerate the gyp files again with `gclient runhooks`.
 
-**Step 3.** Rebuild ffmpeg Dll with `ninja -C out/Release ffmpeg`.
+**Step 4.** Rebuild NW.js with `ninja -C out/Release nwjs`. Then you will get NW.js as well as FFmpeg DLL with proprietary codecs. If you just want to rebuild the DLL, running `ninja -C out/Release ffmpeg` will do. The generated binaries can be found in `out/Release`.
