Allowed segment filename prefix to be specified. See HLS-9
Allowed segment filename prefix to be specified. See HLS-9

--- a/HLS-Stream-Creator.sh
+++ b/HLS-Stream-Creator.sh
@@ -20,7 +20,7 @@
 #   list of conditions and the following disclaimer in the documentation and/or
 #   other materials provided with the distribution.
 # 
-#   Neither the name of the {organization} nor the names of its
+#   Neither the name of Ben Tasker nor the names of his
 #   contributors may be used to endorse or promote products derived from
 #   this software without specific prior written permission.
 # 
@@ -37,10 +37,291 @@
 # 
 ######################################################################################
 
-
-
-
-# The fun begins!
-
-
-
+# Basic config
+OUTPUT_DIRECTORY=${OUTPUT_DIRECTORY:-'./output'}
+
+# Change this if you want to specify a path to use a specific version of FFMPeg
+FFMPEG=${FFMPEG:-'ffmpeg'}
+
+# Number of threads which will be used for transcoding. With newer FFMPEGs and x264
+# encoders "0" means "optimal". This is normally the number of CPU cores.
+NUMTHREADS=${NUMTHREADS:-"0"}
+
+# Video codec for the output video. Will be used as an value for the -vcodec argument
+VIDEO_CODEC=${VIDEO_CODEC:-"libx264"}
+
+# Video codec for the output video. Will be used as an value for the -acodec argument
+AUDIO_CODEC=${AUDIO_CODEC:-"libfdk_aac"}
+
+# Additional flags for ffmpeg
+FFMPEG_FLAGS=${FFMPEG_FLAGS:-""}
+
+# If the input is a live stream (i.e. linear video) this should be 1
+LIVE_STREAM=${LIVE_STREAM:-0}
+
+# Video bitrates to use in output (comma seperated list if you want to create an adaptive stream.)
+# leave null to use the input bitrate
+OP_BITRATES=${OP_BITRATES:-''}
+
+# Determines whether the processing for adaptive streams should run sequentially or not
+NO_FORK=${NO_FORK:-0}
+
+# Lets put our functions here
+
+
+## Output the script's CLI Usage
+#
+#
+function print_usage(){
+
+cat << EOM
+HTTP Live Stream Creator
+Version 1
+
+Copyright (C) 2013 B Tasker, D Atanasov
+Released under BSD 3 Clause License
+See LICENSE
+
+
+Usage: HLS-Stream-Creator.sh -[lf] [-c segmentcount] -i [inputfile] -s [segmentlength(seconds)] -o [outputdir] -b [bitrates]  [-p filename]
+
+	-i	Input file
+	-s	Segment length (seconds)
+	-o	Output directory (default: ./output)
+	-l	Input is a live stream
+	-c	Number of segments to include in playlist (live streams only) - 0 is no limit
+	-b	Output video Bitrates (comma seperated list for adaptive streams)
+	-f	Foreground encoding only (don't fork the encoding processes into the background - adaptive non-live streams only)
+	-p	Playlist filename
+	-t	Segment filename prefix
+
+Deprecated Legacy usage:
+	HLS-Stream-Creator.sh inputfile segmentlength(seconds) [outputdir='./output']
+
+EOM
+
+exit
+
+}
+
+
+function createStream(){
+# For VoD and single bitrate streams the variables we need will exist in Global scope.
+# for live adaptive streams though, that won't be the case, so we need to take them as arguments
+# Some are global though, so we'll leave those as is
+
+playlist_name="$1"
+output_name="$2"
+bitrate="$3"
+
+$FFMPEG -i "$INPUTFILE" \
+    -loglevel error -y \
+    -vcodec "$VIDEO_CODEC" \
+    -acodec "$AUDIO_CODEC" \
+    -threads "$NUMTHREADS" \
+    -map 0 \
+    -flags \
+    -global_header \
+    -f segment \
+    -segment_list "$playlist_name" \
+    -segment_time "$SEGLENGTH" \
+    -segment_format mpeg_ts \
+    $bitrate \
+    $FFMPEG_ADDITIONAL \
+    $FFMPEG_FLAGS \
+    "$OUTPUT_DIRECTORY/$output_name"
+}
+
+
+function createVariantPlaylist(){
+playlist_name="$1"
+echo "#EXTM3U" > "$playlist_name"
+}
+
+
+function appendVariantPlaylistentry(){
+playlist_name=$1
+playlist_path=$2
+playlist_bw=$(( $3 * 1000 )) # bits not bytes :)
+
+cat << EOM >> "$playlist_name"
+#EXT-X-STREAM-INF:BANDWIDTH=$playlist_bw
+$playlist_path
+EOM
+
+}
+
+
+function awaitCompletion(){
+# Monitor the encoding pids for their completion status
+while [ ${#PIDS[@]} -ne 0 ]; do
+    # Calculate the length of the array
+    pid_length=$((${#PIDS[@]} - 1))
+
+    # Check each PID in the array
+    for i in `seq 0 $pid_length`
+    do
+	  # Test whether the pid is still active
+	  if ! kill -0 ${PIDS[$i]} 2> /dev/null
+	  then
+		echo "Encoding for bitrate ${BITRATE_PROCESSES[$i]}k completed"
+		unset BITRATE_PROCESSES[$i]
+		unset PIDS[$i]
+	  fi
+    done
+    PIDS=("${PIDS[@]}") # remove any nulls
+    sleep 1
+done
+}
+
+
+# This is used internally, if the user wants to specify their own flags they should be
+# setting FFMPEG_FLAGS
+FFMPEG_ADDITIONAL=''
+LIVE_SEGMENT_COUNT=0
+
+# Get the input data
+
+# This exists to maintain b/c
+LEGACY_ARGS=1
+
+# If even one argument is supplied, switch off legacy argument style
+while getopts "i:o:s:c:b:p:t:lf" flag
+do
+	LEGACY_ARGS=0
+        case "$flag" in
+                i) INPUTFILE="$OPTARG";;
+                o) OUTPUT_DIRECTORY="$OPTARG";;
+                s) SEGLENGTH="$OPTARG";;
+		l) LIVE_STREAM=1;;
+		c) LIVE_SEGMENT_COUNT="$OPTARG";;
+		b) OP_BITRATES="$OPTARG";;
+		f) NO_FORK=1;;
+		p) PLAYLIST_PREFIX="$OPTARG";;
+		t) SEGMENT_PREFIX="$OPTARG";;
+        esac
+done
+
+
+if [ "$LEGACY_ARGS" == "1" ]
+then
+  # Old Basic Usage is 
+  # cmd.sh inputfile segmentlength 
+
+  INPUTFILE=${INPUTFILE:-$1}
+  SEGLENGTH=${SEGLENGTH:-$2}
+  if ! [ -z "$3" ]
+  then
+    OUTPUT_DIRECTORY=$3
+  fi
+fi
+
+
+# Check we've got the arguments we need
+if [ "$INPUTFILE" == "" ] || [ "$SEGLENGTH" == "" ]
+then
+  print_usage
+fi
+
+# FFMpeg is a pre-requisite, so let check for it
+if hash $FFMPEG 2> /dev/null
+then
+  # FFMpeg exists
+  echo "ffmpeg command found.... continuing"
+else
+  # FFMPeg doesn't exist, uh-oh!
+  echo "Error: FFmpeg doesn't appear to exist in your PATH. Please addresss and try again"
+  exit 1
+fi
+
+# Check output directory exists otherwise create it
+if [ ! -w $OUTPUT_DIRECTORY ]
+then
+  echo "Creating $OUTPUT_DIRECTORY"
+  mkdir -p $OUTPUT_DIRECTORY
+fi
+
+if [ "$LIVE_STREAM" == "1" ]
+then
+    FFMPEG_ADDITIONAL+="-segment_list_flags +live"
+
+    if [ "$LIVE_SEGMENT_COUNT" -gt 0 ]
+    then
+	FFMPEG_ADDITIONAL+=" -segment_list_size $LIVE_SEGMENT_COUNT"
+    fi
+fi
+
+
+# Pulls file name from INPUTFILE which may be an absolute or relative path.
+INPUTFILENAME=${INPUTFILE##*/}
+
+# If a prefix hasn't been specified, use the input filename
+PLAYLIST_PREFIX=${PLAYLIST_PREFIX:-$INPUTFILENAME}
+SEGMENT_PREFIX=${SEGMENT_PREFIX:-$PLAYLIST_PREFIX}
+
+# Set the bitrate
+if [ ! "$OP_BITRATES" == "" ]
+then
+      # Make the bitrate list easier to parse
+      OP_BITRATES=${OP_BITRATES//,/$'\n'}
+
+      # Create an array to house the pids for backgrounded tasks
+      declare -a PIDS
+      declare -a BITRATE_PROCESSES
+
+      # Get the variant playlist created
+      createVariantPlaylist "$OUTPUT_DIRECTORY/${PLAYLIST_PREFIX}_master.m3u8"
+      for br in $OP_BITRATES
+      do
+	    appendVariantPlaylistentry "$OUTPUT_DIRECTORY/${PLAYLIST_PREFIX}_master.m3u8" "${PLAYLIST_PREFIX}_${br}.m3u8" "$br"
+      done
+
+      # Now for the longer running bit, transcode the video
+      for br in $OP_BITRATES
+      do
+	      BITRATE="-b:v ${br}k -bufsize ${br}k"
+	      # Finally, lets build the output filename format
+	      OUT_NAME="${SEGMENT_PREFIX}_${br}_%05d.ts"
+	      PLAYLIST_NAME="$OUTPUT_DIRECTORY/${PLAYLIST_PREFIX}_${br}.m3u8"
+
+	      echo "Generating HLS segments for bitrate ${br}k - this may take some time"
+
+	      if [ "$NO_FORK" == "0" ] || [ "$LIVE_STREAM" == "1" ]
+	      then
+		      # Processing Starts
+		      createStream "$PLAYLIST_NAME" "$OUT_NAME" "$BITRATE" &
+		      PID=$!
+		      PIDS=(${PIDS[@]} $PID)
+		      BITRATE_PROCESSES=(${BITRATE_PROCESSES[@]} $br)
+	      else
+		      createStream "$PLAYLIST_NAME" "$OUT_NAME" "$BITRATE"
+	      fi
+	      # Will deal with exit statuses shortly.
+	      #|| exit 1
+
+      done
+
+      if [ "$NO_FORK" == "0" ] || [ "$LIVE_STREAM" == "1" ]
+      then
+	    # Monitor the background tasks for completion
+	    echo "All transcoding processes started, awaiting completion"
+	    awaitCompletion
+      fi
+
+else
+
+  # No bitrate specified
+
+  # Finally, lets build the output filename format
+  OUT_NAME="${SEGMENT_PREFIX}_%05d.ts"
+  PLAYLIST_NAME="$OUTPUT_DIRECTORY/${PLAYLIST_PREFIX}.m3u8"
+
+  echo "Generating HLS segments - this may take some time"
+
+  # Processing Starts
+
+  createStream "$PLAYLIST_NAME" "$OUT_NAME" "$BITRATE"
+
+
+fi
+

file:a/README.md -> file:b/README.md
--- a/README.md
+++ b/README.md
@@ -1,5 +1,130 @@
 HLS-Stream-Creator
 ==================
 
-Simple Bash Script to take a media file, segment it and create an M3U8 playlist for serving using HLS
+Introduction
+-------------
 
+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.
+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
+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.
+
+
+
+Usage
+------
+
+Usage is incredibly simple
+
+```
+./HLS-Stream-Creator.sh -[lf] [-c segmentcount] -i [inputfile] -s [segmentlength(seconds)] -o [outputdir] -b [bitrates]
+
+
+Deprecated Legacy usage:
+	HLS-Stream-Creator.sh inputfile segmentlength(seconds) [outputdir='./output']
+
+```
+
+So to split a video file called *example.avi* into segments of 10 seconds, we'd run
+
+```
+./HLS-Stream-Creator.sh -i example.avi -s 10
+```
+
+**Arguments**
+
+```
+    Mandatory Arguments:
+
+	-i [file]	Input file
+	-s [s]  	Segment length (seconds)
+
+    Optional Arguments:
+
+	-o [directory]	Output directory (default: ./output)
+	-c [count]	Number of segments to include in playlist (live streams only) - 0 is no limit
+	-b [bitrates]	Output video Bitrates in kb/s (comma seperated list for adaptive streams)
+	-l		Input is a live stream
+	-f		Foreground encoding only (adaptive non-live streams only)
+```
+
+
+Adaptive Streams
+------------------
+
+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.
+
+In order to create seperate bitrate streams, pass a comma seperated list in with the *-b* option
+
+```
+./HLS-Stream-Creator.sh -i example.avi -s 10 -b 28,64,128,256
+```
+
+By default, transcoding for each bitrate will be forked into the background - if you wish to process the bitrates sequentially, pass the *-f* option
+
+```
+./HLS-Stream-Creator.sh -i example.avi -s 10 -b 28,64,128,256 -f
+```
+
+In either case, in accordance with the HLS spec, the audio bitrate will remain unchanged
+
+
+Output
+-------
+
+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
+
+>\#EXTM3U  
+>\#EXT-X-MEDIA-SEQUENCE:0  
+>\#EXT-X-VERSION:3  
+>\#EXT-X-TARGETDURATION:10  
+>\#EXTINF:10, no desc  
+>example_00001.ts  
+>\#EXTINF:10, no desc  
+>example_00002.ts  
+>\#EXTINF:10, no desc  
+>example_00003.ts  
+>\#EXTINF:5, no desc  
+>example_00004.ts  
+>\#EXT-X-ENDLIST
+
+
+
+Using a Specific FFMPEG binary
+-------------------------------
+
+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
+
+```
+FFMPEG='/path/to/different/ffmpeg'
+```
+
+
+Additional Environment Variables
+-------------------------------
+
+There are few environment variables which can control the ffmpeg behaviour.
+
+* `VIDEO_CODEC` - The encoder which will be used by ffmpeg for video streams. Examples: _libx264_, _nvenc_
+* `AUDIO_CODEC` - Encoder for the audio streams. Examples: _aac_, _libfdk_acc_, _mp3_, _libfaac_
+* `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.
+* `FFMPEG_FLAGS` - Additional flags for ffmpeg. They will be passed without any modification.
+
+Example usage:
+
+```
+export VIDEO_CODEC="nvenc"
+export FFMPEG_FLAGS="-pix_fmt yuv420p -profile:v"
+./HLS-Stream-Creator.sh example.avi 10
+```
+
+License
+--------
+
+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)
+
+
+Issue Tracking
+----------------
+
+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.
+