Update README to contain more information on encrypted streams (HLS-20)
[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
18 ```
Ben Tasker 19 ./HLS-Stream-Creator.sh inputfile segmentlength(seconds) [outputdir='./output']
Ben Tasker 20 ```
21
22 So to split a video file called *example.avi* into segments of 10 seconds, we'd run
23
24 ```
bentasker 25 ./HLS-Stream-Creator.sh example.avi 10
26 ```
27
28
29
Ben Tasker 30 Output
bentasker 31 -------
32
Ben Tasker 33 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
34
35 >\#EXTM3U
Ben Tasker 36 >\#EXT-X-MEDIA-SEQUENCE:0
37 >\#EXT-X-VERSION:3
Ben Tasker 38 >\#EXT-X-TARGETDURATION:10
Henric Andersson 39 >\#EXTINF:10, no desc
Ben Tasker 40 >example_00001.ts
41 >\#EXTINF:10, no desc
42 >example_00002.ts
Ben Tasker 43 >\#EXTINF:10, no desc
44 >example_00003.ts
B Tasker 45 >\#EXTINF:5, no desc
Ben Tasker 46 >example_00004.ts
Ben Tasker 47 >\#EXT-X-ENDLIST
48
Ben Tasker 49
50
B Tasker 51 Using a Specific FFMPEG binary
Henric Andersson 52 -------------------------------
53
54 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
Ben Tasker 55
56 ```
57 FFMPEG='/path/to/different/ffmpeg'
58 ```
59
60
61 Additional Environment Variables
Ben Tasker 62 -------------------------------
Ben Tasker 63
64 There are few environment variables which can control the ffmpeg behaviour.
65
66 * `VIDEO_CODEC` - The encoder which will be used by ffmpeg for video streams. Examples: _libx264_, _nvenc_
67 * `AUDIO_CODEC` - Encoder for the audio streams. Examples: _aac_, _libfdk_acc_, _mp3_, _libfaac_
68 * `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.
69 * `FFMPEG_FLAGS` - Additional flags for ffmpeg. They will be passed without any modification.
70
71 Example usage:
72
Ben Tasker 73 ```
74 export VIDEO_CODEC="nvenc"
Ben Tasker 75 export FFMPEG_FLAGS="-pix_fmt yuv420p -profile:v"
bentasker 76 ./HLS-Stream-Creator.sh example.avi 10
77 ```
B Tasker 78
79 License
80 --------
81
82 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)
83
84
85