README.md
1# ExoPlayer Flac extension #
2
3The Flac extension provides `FlacExtractor` and `LibflacAudioRenderer`, which
4use libFLAC (the Flac decoding library) to extract and decode FLAC audio.
5
6## License note ##
7
8Please note that whilst the code in this repository is licensed under
9[Apache 2.0][], using this extension also requires building and including one or
10more external libraries as described below. These are licensed separately.
11
12[Apache 2.0]: https://github.com/google/ExoPlayer/blob/release-v2/LICENSE
13
14## Build instructions (Linux, macOS) ##
15
16To use this extension you need to clone the ExoPlayer repository and depend on
17its modules locally. Instructions for doing this can be found in ExoPlayer's
18[top level README][].
19
20In addition, it's necessary to build the extension's native components as
21follows:
22
23* Set the following environment variables:
24
25```
26cd "<path to exoplayer checkout>"
27EXOPLAYER_ROOT="$(pwd)"
28FLAC_EXT_PATH="${EXOPLAYER_ROOT}/extensions/flac/src/main"
29```
30
31* Download the [Android NDK][] and set its location in an environment variable.
32 This build configuration has been tested on NDK r20.
33
34```
35NDK_PATH="<path to Android NDK>"
36```
37
38* Download and extract flac-1.3.2 as "${FLAC_EXT_PATH}/jni/flac" folder:
39
40```
41cd "${FLAC_EXT_PATH}/jni" && \
42curl https://ftp.osuosl.org/pub/xiph/releases/flac/flac-1.3.2.tar.xz | tar xJ && \
43mv flac-1.3.2 flac
44```
45
46* Build the JNI native libraries from the command line:
47
48```
49cd "${FLAC_EXT_PATH}"/jni && \
50${NDK_PATH}/ndk-build APP_ABI=all -j4
51```
52
53[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md
54[Android NDK]: https://developer.android.com/tools/sdk/ndk/index.html
55
56## Build instructions (Windows) ##
57
58We do not provide support for building this extension on Windows, however it
59should be possible to follow the Linux instructions in [Windows PowerShell][].
60
61[Windows PowerShell]: https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell
62
63## Using the extension ##
64
65Once you've followed the instructions above to check out, build and depend on
66the extension, the next step is to tell ExoPlayer to use the extractor and/or
67renderer.
68
69### Using `FlacExtractor` ###
70
71`FlacExtractor` is used via `ExtractorMediaSource`. If you're using
72`DefaultExtractorsFactory`, `FlacExtractor` will automatically be used to read
73`.flac` files. If you're not using `DefaultExtractorsFactory`, return a
74`FlacExtractor` from your `ExtractorsFactory.createExtractors` implementation.
75
76### Using `LibflacAudioRenderer` ###
77
78* If you're passing a `DefaultRenderersFactory` to `SimpleExoPlayer.Builder`,
79 you can enable using the extension by setting the `extensionRendererMode`
80 parameter of the `DefaultRenderersFactory` constructor to
81 `EXTENSION_RENDERER_MODE_ON`. This will use `LibflacAudioRenderer` for
82 playback if `MediaCodecAudioRenderer` doesn't support the input format. Pass
83 `EXTENSION_RENDERER_MODE_PREFER` to give `LibflacAudioRenderer` priority over
84 `MediaCodecAudioRenderer`.
85* If you've subclassed `DefaultRenderersFactory`, add a `LibflacAudioRenderer`
86 to the output list in `buildAudioRenderers`. ExoPlayer will use the first
87 `Renderer` in the list that supports the input media format.
88* If you've implemented your own `RenderersFactory`, return a
89 `LibflacAudioRenderer` instance from `createRenderers`. ExoPlayer will use the
90 first `Renderer` in the returned array that supports the input media format.
91* If you're using `ExoPlayer.Builder`, pass a `LibflacAudioRenderer` in the
92 array of `Renderer`s. ExoPlayer will use the first `Renderer` in the list that
93 supports the input media format.
94
95Note: These instructions assume you're using `DefaultTrackSelector`. If you have
96a custom track selector the choice of `Renderer` is up to your implementation,
97so you need to make sure you are passing an `LibflacAudioRenderer` to the
98player, then implement your own logic to use the renderer for a given track.
99
100## Using the extension in the demo application ##
101
102To try out playback using the extension in the [demo application][], see
103[enabling extension decoders][].
104
105[demo application]: https://exoplayer.dev/demo-application.html
106[enabling extension decoders]: https://exoplayer.dev/demo-application.html#enabling-extension-decoders
107
108## Links ##
109
110* [Javadoc][]: Classes matching `com.google.android.exoplayer2.ext.flac.*`
111 belong to this module.
112
113[Javadoc]: https://exoplayer.dev/doc/reference/index.html
114