Update README to include input flags env variable
[HLS-Stream-Creator.git] / README.md
1 HLS-Stream-Creator
2 ==================
3
bentasker 4 Introduction
5 -------------
6
7 HLS-Stream-Creator is a simple BASH Script designed to take a media file, segment it and create an M3U8 playlist for serving using HLS.
8 There are numerous tools out there which are far better suited to the task, and offer many more options. This project only exists because I was asked to look
9 into HTTP Live Streaming in depth, so after reading the [IETF Draft](http://tools.ietf.org/html/draft-pantos-http-live-streaming-11 "HLS on IETF") I figured I'd start with the basics by creating a script to encode arbitrary video into a VOD style HLS feed.
10
11
12
13 Usage
14 ------
15
16 Usage is incredibly simple
17
B Tasker 18 ```
Ben Tasker 19 ./HLS-Stream-Creator.sh -[lf] [-c segmentcount] -i [inputfile] -s [segmentlength(seconds)] -o [outputdir] -b [bitrates]
B Tasker 20
Ben Tasker 21
22 Deprecated Legacy usage:
bentasker 23 HLS-Stream-Creator.sh inputfile segmentlength(seconds) [outputdir='./output']
24
25 ```
B Tasker 26
bentasker 27 So to split a video file called *example.avi* into segments of 10 seconds, we'd run
Ben Tasker 28
29 ```
Ben Tasker 30 ./HLS-Stream-Creator.sh -i example.avi -s 10
31 ```
Ben Tasker 32
Henric Andersson 33 **Arguments**
Ben Tasker 34
35 ```
36 Mandatory Arguments:
Ben Tasker 37
38 -i [file] Input file
B Tasker 39 -s [s] Segment length (seconds)
Ben Tasker 40
Ben Tasker 41 Optional Arguments:
42
Ben Tasker 43 -o [directory] Output directory (default: ./output)
44 -c [count] Number of segments to include in playlist (live streams only) - 0 is no limit
B Tasker 45 -b [bitrates] Output video Bitrates in kb/s (comma seperated list for adaptive streams)
Henric Andersson 46 -p [name] Playlist filename prefix
47 -t [name] Segment filename prefix
48 -l Input is a live stream
Ben Tasker 49 -f Foreground encoding only (adaptive non-live streams only)
50 -S Name of a subdirectory to put segments into
51 ```
52
53
54 Adaptive Streams
Ben Tasker 55 ------------------
Ben Tasker 56
57 As of [HLS-6](http://projects.bentasker.co.uk/jira_projects/browse/HLS-6.html) the script can now generate adaptive streams with a top-level variant playlist for both VoD and Linear input streams.
B Tasker 58
59 In order to create seperate bitrate streams, pass a comma seperated list in with the *-b* option
Ben Tasker 60
61 ```
62 ./HLS-Stream-Creator.sh -i example.avi -s 10 -b 28,64,128,256
B Tasker 63 ```
64
Ben Tasker 65 By default, transcoding for each bitrate will be forked into the background - if you wish to process the bitrates sequentially, pass the *-f* option
B Tasker 66
67 ```
68 ./HLS-Stream-Creator.sh -i example.avi -s 10 -b 28,64,128,256 -f
69 ```
70
71 In either case, in accordance with the HLS spec, the audio bitrate will remain unchanged
B Tasker 72
B Tasker 73
74 Output
75 -------
76
77 As of version 1, the HLS resources will be output to the directory *output*. These will consist of video segments encoded in H.264 with AAC audio and an m3u8 file in the format
B Tasker 78
79 >\#EXTM3U
B Tasker 80 >\#EXT-X-MEDIA-SEQUENCE:0
81 >\#EXT-X-VERSION:3
82 >\#EXT-X-TARGETDURATION:10
83 >\#EXTINF:10, no desc
bentasker 84 >example_00001.ts
85 >\#EXTINF:10, no desc
B Tasker 86 >example_00002.ts
87 >\#EXTINF:10, no desc
88 >example_00003.ts
89 >\#EXTINF:5, no desc
90 >example_00004.ts
91 >\#EXT-X-ENDLIST
B Tasker 92
B Tasker 93
94
95 Using a Specific FFMPEG binary
96 -------------------------------
97
98 There may be occasions where you don't want to use the *ffmpeg* that appears in PATH. At the top of the script, the ffmpeg command is defined, so change this to suit your needs
B Tasker 99
100 ```
101 FFMPEG='/path/to/different/ffmpeg'
102 ```
103
104
105 Additional Environment Variables
106 -------------------------------
B Tasker 107
B Tasker 108 There are few environment variables which can control the ffmpeg behaviour.
bentasker 109
110 * `VIDEO_CODEC` - The encoder which will be used by ffmpeg for video streams. Examples: _libx264_, _nvenc_
111 * `AUDIO_CODEC` - Encoder for the audio streams. Examples: _aac_, _libfdk_acc_, _mp3_, _libfaac_
B Tasker 112 * `NUMTHREADS` - A number which will be passed to the `-threads` argument of ffmpeg. Newer ffmpegs with modern libx264 encoders will use the optimal number of threads by default.
bentasker 113 * `FFMPEG_FLAGS` - Additional flags for ffmpeg. They will be passed without any modification.
B Tasker 114
115 Example usage:
116
117 ```
118 export VIDEO_CODEC="nvenc"
119 export FFMPEG_FLAGS="-pix_fmt yuv420p -profile:v"
120 ./HLS-Stream-Creator.sh example.avi 10
121 ```
122
123 License
124 --------
125
126 HLS-Stream-Creator is licensed under the [BSD 3 Clause License](http://opensource.org/licenses/BSD-3-Clause) and is Copyright (C) 2013 [Ben Tasker](http://www.bentasker.co.uk)
bentasker 127
bentasker 128
129 Issue Tracking
130 ----------------
131
132 Although the Github issue tracker can be used, the bulk of project management (such as it is) happens in JIRA. See [projects.bentasker.co.uk](http://projects.bentasker.co.uk/jira_projects/browse/HLS.html) for a HTML mirror of the tracking.
133