Embed an HLS adaptive streaming audio

An HLS adaptive streaming audio consists of various playlists (m3u8 manifests) with audio segments to serve different bitrate versions depending on the internet connection of the visitor. You can let the Elastic Transcoder service in the AWS console create these manifests and audio segments if you don't have the software or experience to convert a master audio into HLS.
Manifests contain hardcoded links, therefore you can normally only create public audio segments as opposed to the other protocols. However, there is a small loophole we found: You can keep the bucket and the files private and only make the web distribution public. That way the files remain safe in the bucket, although they are accessible via the web distribution. Because HLS exists of audio segments of 10 seconds each, illegally downloading them is quite a job, therefore the risk of stealing is somewhat diminished. 

Automated hacker scripts can't get a list of items via the web distribution because an item can only be accessed when you know its name. Nor can someone embed the link to a m3u8 playlist in a player because only your site has permission to access it. So, leeching is prevented this way.

Footprint Player with VideoJS serves HLS it via HTML5 using CORS headers because Flash will be deprecated by most browsers quite soon. Contrary to the other audio formats, HLS is quite complicated to set up. If you run into trouble, This email address is being protected from spambots. You need JavaScript enabled to view it. isn't far away. :-)

Setting up CORS Headers

The first thing you need to do is to follow this tutorial to set CORS headers in your bucket and web distribution in order to make access to the HLS segments HTML5 compatible. When you have done that, come back here and proceed.

How to create manifests and audio segments using Elastic transcoder

Although you can create audio segments with a audio converter, Elastic transcoder makes life easy for you by creating the segments and the relevant manifests in one go. It also goes exceptionally quickly. So, we thought it would be worthwhile to explain how it works: What you need to start with is to have 2 buckets:

  1. A private bucket that contains the master audio you want to process.
  2. A private bucket for the output of the audio in segments and manifests.

Creating the buckets
Whether you have already created buckets or not, it is best to have separate buckets for HLS adaptive streaming for organizational reasons as this media type requires quite a few files. If you haven't followed the Preparations upfront for Footprint Player 1.x, please do so in order to know how to create a bucket.
To make it easy to recognize the function of each bucket later on, best use a naming convention like this:

  1. mybucket-input > used for master audio's.
  2. mybucket-hls > used for audio segments and m3u8 manifests.

 Create those buckets and return here. You should have something like this now:

AWS bucket list

Upload the master audio

Open the mybucket-input bucket and Upload the master audio to the bucket :


Click the Upload button and locate your audio via the Add files button or just drag it into the folder icon:  


Then interface changes as soon as your audio is selected:


This screenshot show a video, but in your cse it will be a .wav, aiff,... Click Next (right bottom).  The following options appear:


Check that Don not grant public read access to this object(s) is selected (normally it is).
Click Next. Now you get quite a few options:


Makes sure the Standard Storage class is selected.  Other options might be tempting but are less reliable.
Scroll down until you see Encryption:


Default this is set to None, but we recommend to select Amazon S3 master-key or AWS KMS master-key.
See How to protect data with Server side AES-encryption to understand the difference between the two. We recommend for master audios to use Amazon S3 master-key since master audios are not used for embedding and you may delete them when you are done, unless you want to keep them as a backup.
Make your choice. The next Header and Tag section are not important, just click Next.  The properties for the master audio are shown:


Click Upload. A progress bar shows how far the upload is evolved:


Don't navigate away from the page until it is done, although you can do other stuff on your computer in the meanwhile. Once the audio is uploaded, it is automatically listed on the left. We we are going to use Elastic Transcoder of AWS to convert that audio in chunks of 10 seconds which will be placed in the other bucket.

Creating a M3u8 manifest and process the audio

Elastic Transcoder is an online video and audio converter with many options. Although you can use your own audio editor, Elastic transcoder is very fast and creates the m3u8 manifests for you. What it involves:

  1. Create a Pipeline, which determines the input and output buckets and the Preset to use.
  2. Create a Job, to break up the audio in segments and create the m3u8 manifest in one go.

If that sounds like Chinese to you, don't worry, all will be explained.

1. Creating a Pipeline

Select the Elastic Transcoder service from the list (you don't need to sign up for this) or use the search box to find it:

Elastic Transcoder service

On the left, you see links to the Pipeline, Jobs and Presets:


Possibly, you have already Pipelines setup, which are listed on the right.  But for HLS adaptive audio streaming, we need to setup a new one. Click the Create New Pipeline button. In the following screen, fill in the details as described below:

hls audio

Pipeline Name: Give this a convenient name to remember. 

Input Bucket: When you click in the field, you get a dropdown with buckets. Select the input bucket which contains your audio. (in hte examle, we use 

IAM Role: Leave as is. If you don't have one already, it will be created for you.

Bucket: is where the converted segments of the audio and the m3u8 manifests are placed. In our example mybucket-hls.

Storage class: Standard. Other options are not useful in this case.

The next step is not necessary, although Elestic Transocder may throw an error if you don't fill it in. 


Select a bucket if you getan error upon clicking the blue Create Pipeline button (bottom right of the page).

The next thing we have to do is create custom presets for HLS audio.

2. Create a Job

This is where everything is going to happen. With a Job, you create the audio segments and the m3u8 manifests. Click on the link Job on the left and click on the Create Job button:


In the following panel, fill in the first group of details:

hls audio3

Pipeline: Select the one you just created.

Output Key Prefix: Optional, but to organize HLS files properly, it is best to put them in a folder. When you fill this in, the folder is automatically created on the fly. Don't forget the trailing slash.

Input Key: Select the audio by clicking in that field to open the dropdown box with existing audios in the mybucket-input bucket.

Scroll down to Output Details:

hls audio4

Preset: The system HLS presets are fine. Select first System preset: HLS Audio 160k.

Segment duration: Apple recommends segments of 10 seconds. You can change that if you like, but this is the ideal length.

Output Key: Give a prefix for each segment.  Since you chose the 400 kbs bitrate preset, indicate it more or less as shown.

Segment Filename Preview: is a preview of the segment names influenced by the previous field.

Create Thumbnails: Leave it to No, this resolution is not good enough to create a poster image.

Ouput Rotation: Auto.

Now, we setup an additonal preset for 64kbs. Scroll a little down until you see the +Add Another Output link:

hls audio5

A new group of Output Details shows up. Repeat the same as previously, but this time select System Preset HLS audo 64k, Segmentation: 10, Output Key: something similar like hls_64k. 
With this done, we create 3 birate versions in one go, respectively 160k and 64k, neatly named according to the Output key prefixes. But we are not done yet with this Job. We have to create the manifests as well. 
Scroll down to where you see a button Add Playlist:

Add playlist

In the following part you get the following fields:

hls audio6

Master Playlist Name: Usually we call this index since it is the master manifest which will call the others. The .m3u8 extension is automatically added, don't pt it in that filed or it becomes index.m3u8.m3u8 !

Playlist Format: Select HLSv3

Outputs in Master Playlist: Select first the 160k version. Now click the + sign next to that field to add the following Output:

hls audio7

This time, select hls_64k.  This will create separate manifest for each bitrate version. Then scroll down until you see the blue Create Job button.  Click on it.
Elastic Transcoder now processes everything for you.  It shows a status of the job and all the details involved.
You can refresh the screen from time to time to see if it is finished yet. If the status is Complete, the job is done. 

You can check the bucket, to see everything is there. Go to the S3 service and select the bucket which should contain the audio segments, in this example mybucket-hls. You will notice that there is a folder with the name you designated in the Output Key Prefix. Click on the folder to open it. There should be a range of .ts files and .m3u8 manifests. The one we will need is the index. m3u8 manifest to load into the player.  Since we have setup the bucket and web distribution with CORS headers, we don't have to rely on Flash, hence we don't need to create a crossdomain file.

We are ready now to embed the HLS adaptive streaming audio.

Embed HLS adaptive streaming audio

We provide here two methods of working of which the wizard is the easiest to start with. Select the method you want to use below:

Using the wizard

For more info about where the wizard is located ad how it works, see Using the shortcode wizards
Click the Insert Footprint Player button in the article editor. This opens the Wizard popup. As a mininum, we need to fill in:

  1. Title (title in shortcode)
  2. Media Type (mediatype in shortcode)
  3. Media File (mediafile in shortcode)
  4. Source 2 (source2 in shortcode)
  5. Web distribution (bucket in shortcode)
  6. URL expiration (expireseconds in shortcode)
  7. Aspect ratio

Below you see highlighted the fields that are important:

wizard hls audio2

Title is not required here but it is useful for SEO and to remind you what the audio is about. The title can contain any alphanumeric characters, including spaces. This is the only attribute that can contain spaces. For instance: Download my book. Don't place spaces anywhere else in the fields.

Media Type: Select Audio HLS, Mpeg-dash, mp3, m4a, wav. or leave as is, if it is already set in the default settings.

Media File is the full path to the HLS manifest. Since the audio segments and manifests are all together in the same folder that we generated using Elastic Transcoder, we construct the link to the main manifest like this:  https://dxxxxx.cloudfront.net/myfolder/index.m3u8 where myfolder is replaced by the name you chose during the pricess of conversion and https://dxxxxx.cloudfront.net is the web distribution for the bucket mybucket-hls.

Source 2 is a fallback option for HLS adaptive streaming.  Although most browsers support HLS via HTML5, some don't. If you want to make sure they are served as well, you can set the an alternative version like mp3. It's easier to download a mp3 audio, so filling in this field is a matter of choice. You might also say to your customers that Firefox or Chrome is required. In any case, don't place an mp3 version in the same bucket as that of the HLS segments. Consider using a bucket with a AWS KMS master-key (see How to protect data with Server side AES-encryption).
Like the Media File field, give a full path to the mp3 file.

URL expiration is for HLS not really necessary, but it doesn't hurt. That said, if you use a fallback (source2 and/or source3), it is a must. This is a numerical value in seconds to create the signed URL, like expireseconds=600.
You can set this as a default in the default settings if you like.

Aspect ratio determines the relationship between width and height. It accepts values like 16:9, 16:3, 4:3 where the first figure is width and the second is the height (first figure divided by the second). Example: 16:4 means that the height is one fourth of the width. Since Fooptrint Player is responsive by default, it is not possible to set fixed values.

You should now have something like this:

wizard hls audio3

All other attributes are explained in the default settings and Footprint Player - Short codes
Poster Image (posterimage in shortcode) can make the look of the audio player more interesting. So, you can prepare an image and link to it via that field. If you uploaded the image to the images folder of your Joomla installation, then just give the name of the file or preceded by a folder name if appropriate. External images require the full path.

When you are ready, click Insert Shortcode. This generates the shortcode for you, like this example:

{footprint }title=My hls audio about ducks|mediatye=audio|mediafile=https://dxxxxxx.cloudfront.net/myfolder/index.m3u8|source=https://danother.cloudfront.net/myaudio.mp3|expireseconds=600{/footprint}

Does it work for you?

Working with Shortcode

Embedding a HLS adaptive streaming audio is the same process as embedding a progressive download audio with the difference that we link to a manifest playlist instead of a audio directly.

Open an article and place the cursor where you want to add the audio.
Note: in all shortcode examples on this site, there is a space after footprint right before the end of the opening tag. This is to prevent the extension from showing a player on this site. Therefore, remove this space on your site if you copy the shortcode from here.

{footprint }....{/footprint}

The minimum attributes you probably need are:

  1. mediatype
  2. title
  3. mediafile
  4. width
  5. aspectratio
  6. posterimage
  7. expireseconds

Basic example shortcode

{footprint }mediatype=audio|title=This is the title|mediafile=https://dxxxxx.cloudfront.net/index.m3u8|aspectratio=16:3{/footprint}

If set as default in the default settings you can leave this out attribute out. The extension will process the shortcode anyway.

title is optional, primarily used for SEO and to remind you what the audio is about.  It can contain any alphanumeric characters, including spaces. This is the only attribute that can contain spaces. Don't place spaces anywhere else in the shortcode.

mediafile is the full path to the manifest. Thus, we get:

{footprint }title=This is the title|mediatype=audio|mediafile=https://dxxxxx.cloudfront.net/presentation/index.m3u8{/footprint}

Aspect ratio determines the relationship between width and height. It accepts values like 16:9, 16:3, 4:3 where the first figure is width and the second is the height (first figure divided by the second). Example: 16:4 means that the height is one fourth of the width. Since Fooptrint Player is responsive by default, it is not possible to set fixed values.

aspectratio can be set with the default settings so that you can leave them out in the shortcode. Go to Extensions > Plugin Manager and locate Content - Footprint Player to set those defaults. Below you find an example with aspectratio excluded:

{footprint }title=This is the title|mediatype=audio|mediafile=https://dxxxxx.cloudfront.net/presentation/index.m3u8{/footprint}

posterimage sets a poster image as the preview as you can see in the screenshot above. If omitted, you get a black rectangle instead.

expireseconds is a numerical value in seconds to create the signed URL for private audio, like expireseconds=600.

Note: in this particular case, signed URLs are purely cosmetic, because the web distribution itself is public.  The player would work without it as well. That said, we recommend to use it anyway.

{footprint }title=This is the title|mediatype=audio|mediafile=https://dxxxxx.cloudfront.net/presentation/index.m3u8|posterimage=https://.....myposter.jpg|expireseconds=800{/footprint}

The full list of shortcode attributes can be found here: S3Media Stream 7 - Shortcodes

Advanced settings

We continue to use the basic example, adding more atrributes as we go along (without source2).

Adding a Wave form

The player can produce a wave form of an audio:


Note that to generate waveforms, the player must read the entire file in order to generate the wave. With lengthy audios this may take a while. During generation, the player isn't active. Therefore, best used for short audios. A workaround is to generate waveform from a lenghty video, take a screenshot and use that as a poster image. It's not the same effect of course, since waveform audios have a special progress cursor:


Audios with a wave form cannot have subtitles/captions, therefore it is best used for music audio.

Adding a watermark

Watermarks can be used sitewide or per instance. Generally, you may want to set this in the default settings, only overriding it where needed. You could have the logo of your site in the default settings, while an individual instance could have an image of a book, linking to a Buy now page. 
This attribute has a set of 3 options that go together: logologopositionlogolink. Yet, they must be divided by a | pipe character, like this:


If you only use the name of the image for the logo, the extension presumes you placed it in the images folder of your site. Subfolders are possible when you include them, like myfolder/mywatermark.png, which resort to: http://mydomain.com/images/mywatermark.png.
It is also possible to link a logo from external locations, like https://dxxxxx.coudfront.net/mywatermark.png
Note: the name watermark.png is reserved for the Dynamic watermark feature which shows the name of the user, IP address and date. This can be activated by downloading the watermark script in the download area. It is a separate script you have to place via FTP. See Dynamic watermark to prevent screen capturing.

The logoposition has 4 locations: top-left, top-right, bottom-left, bottom-right

The logolink is always full path and it can go to any page.

{footprint }mediatype=audio|title=This is the title|mediafile=https://dxxxxx.cloudfront.net/presentation/index.m3u8|posterimage=https://.....myposter.jpg|expireseconds=800|aspectratio=16:9|logo=mywatermark.png|logoposition=top-left|logolink=https://mydomain.com{/footprint}

Adding Captions/Subtitles

You can add subtitles to audios. But for this, you best set the aspectratio to 16:9 or 4:3 and add a background posterimage, because you need space for the subtitle listing and options:


It is even possible to set multiple language versions of subtitles/captions. This has 2 options that belong together; captionslink and captionsstate, Yet, they must be divided by a | pipe character, like the logo attribute. But captionsstate can be set via the Default settings plugin. Therefore, you don't need to add it in the shortcode but you can overrule the default setting if you like.
In order for subtitles to display properly accross browsers, we need to indicate, apart from the name, the language label and the language code. Therefore, we need to use a fixed convention for the name of the subtitle file ( .vtt format only).  For example: mysubtitle-English-en where English is the label for the language and en is the language code. name, language label and language code are divided by a hyphen.

captionsstate (1 or 0) gives the choice to have the subtitles show immediately upon play (Captions behavior), or use the subtile behavior, which requires the user to activate subtitles via the CC button. Default is 0, meaning it doesn't show up automatically. Below an example with one subtitle file andposter image:

{footprint }mediatype=audio|title=This is the title|mediafile=https://dxxxxx.cloudfront.net/presentation/index.m3u8|posterimage=https://.....myposter.jpg|expireseconds=800|aspectratio=16:9|logo=mywatermark.png|logoposition=top-left|logolink=https://mydomain.com|

and here an example with 3 diferent language versions:

{footprint }mediatype=audio|title=This is the title|mediafile=https://dxxxxx.cloudfront.net/presentation/index.m3u8|posterimage=https://.....myposter.jpg|

Note that multiple subtitles are divided by a comma without space. Again, note also that the .vtt extension shouldn't be included. The web tools console will give an error when the naming convention is not respected. It also gives an error is the wrong kind of subtitle file is used or if it contains errors.

If the defaults are set, ommit the last two options, like this:

{footprint }title=This is the title|mediafile=https://dxxxxx.cloudfront.net/presentation/index.m3u8|posterimage=https://.....myposter.jpg||logo=mywatermark.png|logoposition=top-left|logolink=https://mydomain.com|captionslink=mysubtitle-English-en,mysubtitle-Francais-fr,mysubtitle-Deutsch-de|aspectratio=16:9{/footprint}

When you are done adapting the example shortcode, save the article.  Does the audio play on the front end?  Congratulations!
If not, check out below:

Trouble shooting

Problems with shortcodes when pasting

Sometimes, the added code changes into a link.  if that happens, select the link part of the shortcode and break the link because it can prevent the audio from showing up since the editor added unwanted code. You recognize it when it looks like this:

{footprint }title=This is the title|mediafile=https://dxxxxx.cloudfront.net/presentation/index.m3u8|posterimage=https://.....myposter.jpg||logo=mywatermark.png|logoposition=top-left|logolink=https://mydomain.com|captionslink=mysubtitle-English-en,mysubtitle-Francais-fr,mysubtitle-Deutsch-de{/footprint}

Sometimes, the short code is partially linked.  Remove any links within the short code without removing the short code itself.

Hidden formatting in shortcode

Sometimes when you copy and paste short codes from other documents,hidden formatting may be included. The player may show up as a black rectangle or not at all. Check the short code in Code view and remove any formatting.  Or select the shortcode and push the Remove formatting icon.

File cannot be found

You made a typo in the path to the audio or you forgot to include expiringseconds with a private audio.

Format not accepted or a similar message

Something is wrong with the format of the audio. You may need to reconvert it. 

Crossdomain access denied

It generally has nothing to do with crossdomain settings because the player doesn't use Flash the way we have set it up here. Usually a problem with permissions on AWS or a typo in the mediafile field.
This errors may stay in the cache of the browser for some time, so if you corrected the typo, it is possible that it takes a few hours to be resolved. This is an unique issue with HLS.