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