Release NotesUser InterfaceSystem Status
Recent API Changes
Back to All

14 January 2016 - Live Transcoding

about 9 years ago by Encoding.com Product Team

📘

Note

This feature is currently in 'public beta'. The usage price is $1/GB during the beta period.

RTMP media source

Source typeDescription
RTMPrtmp://[user[:password]@]hostname[:port]/[path]

New output format 'live_hls'

Our live hls transcoding outputs are similar to our Advanced HLS outputs.

However, there are several requirements specific to our live capabilities:

  1. Please use only one 'live_hls' output in your API request!
  2. All Source Media Locations must be a valid RTMP-stream.
  3. Any additional media sources would be used as backup source. Transcoding will be switched to the next source after a 30 second timeout.
  4. A timeout longer than 10 minutes will end transcoding.
  5. These features are not available for output:
    • main_source
    • alternate_source
    • fade_in
    • fade_out
    • burnin_timecode
    • audio_normalization
    • copy_nielsen_metadata
    • closed_captions
    • audio_overlay
    • pack_files
  6. These features are not available for live output:
    • 'Dolby Digital +'(eac3) audio codec
    • fade_in
    • fade_out
    • burnin_timecode
    • audio_normalization
    • copy_nielsen_metadata
    • closed_captions
    • audio_overlay
<?xml version="1.0"?>
<query>
    <userid><<id>></userid> <!-- required-->
    <userkey><<key>></userkey> <!-- required-->
    <action>[Action]</action> <!-- required-->
    <format>
        <output>live_hls</output>
        <stream>
            <!-- [Video settings params](/#VideoSettings) -->
            <!-- [Audio settings params](/#AudioSettings) -->
            <audio_codec>[libfaac|ac3|libmp3lame|copy]</audio_codec>
            <!-- [Other format params](/#OtherFormatOptions) -->
            <!-- [Closed Captions params](/#ClosedCaptions) -->
            <!-- [Editing features params](/#EditingFeatures) -->
        </stream>
        <!-- Multiple stream params may be included in live_hls output format -->
        <!-- Maximum number of available streams is 15 -->
        <stream>
           <!-- stream params -->
        </stream>
        <!-- Format fields -->
        <add_event_manifest>[yes|no]</add_event_manifest>
        <manifest_size>[Size]</manifest_size>
        <manifest_offset>[Offset]</manifest_offset>
        <destination>[DestFile]</destination><!-- REQUIRED -->
    </format>
</query>

{
    "query": {
        "userid": "<<id>>",
        "userkey": "<<key>>",
        "action": "[Action]",
        "format": {
            "output": "live_hls",
            "stream": [
                {
                    "audio_codec": "[libfaac|ac3|libmp3lame|copy]"
                },
                "  "
            ],
            "add_event_manifest": "[yes|no]",
            "manifest_size": "[Size]",
            "manifest_offset": "[Offset]",
            "destination": "[DestFile]"
        }
    }
}
Field NameDescriptionAllowed ValuesDefault Values
Format params
add_event_manifestAdds EVENT-type playlist. Event playlists will have filenames that include *.event.m3u8yes, nono
manifest_sizeNumber of chunks in LIVE playlistPositive integer5
manifest_offsetNumber of chunks that would be transcoded before playlist is uploadedPositive integer3
Stream params
If no streams were specified, 9 default streams with parameters recommended by Apple will be used.
Maximum number of available streams is 15
Aceptable params from:

Video settings
 Audio settings
Other format options
 Watermarking
Video rotation
 Cropping
Video overlays
 Text overlays
audio_codecAudio codeclibfaac, ac3, libmp3lamelibfaac

Akamai Live HLS Ingest

Destination typeDescription
Akamai Live HLS Ingest

Live to 'VOD' transcoding

VOD playlists (*.vod.m3u8) will be automatically uploaded to your destination when the Live Transcoding process is finished(using the 'StopLive' request, 'Stop' request, or after error).
Our full suite of VOD features is available for your VOD outputs, just add them to your API request.
In addition, you can specify VOD-only outputs without adding the 'live_hls' output.

📘

Note

'Harmonic' outputs are not supported as a VOD output for HLS.

📘

Note

VOD processing will be started after the 'StopLive' event occurs.

<?xml version="1.0"?>
<query>
    <userid><<id>></userid> <!-- required-->
    <userkey><<key>></userkey> <!-- required-->
    <action>AddMedia</action><!-- REQUIRED -->
    <source>[RTMPSourceURL]</source><!-- REQUIRED -->
    <!-- OPTIONAL live_hls OUTPUT -->
    <format>
        <output>live_hls</output>
        <destination>[DestFile]</destination><!-- REQUIRED -->
    </format>
    <format>
        <output>[VODOutput]</output>
    </format>
</query>

{
    "query": {
        "userid": "<<id>>",
        "userkey": "<<key>>",
        "action": "AddMedia",
        "source": "[RTMPSourceURL]",
        "format": [
            {
                "output": "live_hls",
                "destination": "[DestFile]"
            },
            {
                "output": "[VODOutput]"
            }
        ]
    }
}

StopLive API request

To stop the Live Transcoding process you need to send API requests with specified Media ID and the 'StopLive' API parameter

<?xml version="1.0"?>
<query>
    <userid><<id>></userid><!-- REQUIRED -->
    <userkey><<key>></userkey><!-- REQUIRED -->
    <action>StopLive</action>
    <mediaid>[MediaID]</mediaid><!-- REQUIRED -->
</query>

{
    "query": {
        "userid": "<<id>>",
        "userkey": "<<key>>",
        "action": "StopLive",
        "mediaid": "[MediaID]"
    }
}

Retranslation Endpoints

If you don't have an RTMP broadcasting server, you can use our Retranslation Endpoint service.
To use it you need to use the Endpoint URL, set it as the endpoint in your streaming tool, and set it as Media Source in your API request

Endpoint URL Syntax:

rtmp://rtmp.encoding.com/[EndpointToken]

Add Endpoint

🚧

Note

Maximum number of endpoints is 10.

<?xml version="1.0"?>
<query>
    <userid><<id>></userid><!-- REQUIRED -->
    <userkey><<key>></userkey><!-- REQUIRED -->
    <action>AddStreamEndpoint</action>
</query>

{
    "query": {
        "userid": "<<id>>",
        "userkey": "<<key>>",
        "action": "AddStreamEndpoint"
    }
}

Get Endpoints

<?xml version="1.0"?>
<query>
    <userid><<id>></userid><!-- REQUIRED -->
    <userkey><<key>></userkey><!-- REQUIRED -->
    <action>GetStreamEndpointList</action>
</query>

{
    "query": {
        "userid": "<<id>>",
        "userkey": "<<key>>",
        "action": "GetStreamEndpointList"
    }
}

Delete Endpoints

<?xml version="1.0"?>
<query>
    <userid><<id>></userid><!-- REQUIRED -->
    <userkey><<key>></userkey><!-- REQUIRED -->
    <action>DeleteStreamEndpoint</action>
    <endpoint>[EndpointURL]</endpoint>
</query>

{
    "query": {
        "userid": "<<id>>",
        "userkey": "<<key>>",
        "action": "DeleteStreamEndpoint",
        "endpoint": "[EndpointURL]"
    }
}

Live transcoding notifications

Add new 'notify_live_start' parameter.

Notify_live_start

This can be either an HTTP(S) URL for the script or a 'mailto' link using the email address to send notifications when the live stream is ready for playback.

Callback Format for notify_live_start

<?xml version="1.0"?>
<result>
    <mediaid>[MediaID]</mediaid>
    <taskid>[TaskID]</taskid>
    <destination>[DestinationLink]</destination>
    <status>[LiveStatus]</status>
</result>

{
    "result": {
        "mediaid": "[MediaID]",
        "taskid": "[TaskID]",
        "destination": "[DestinationLink]",
        "status": "[LiveStatus]"
    }
}
FieldDescription
MediaIDA unique identifier of the media
TaskIDA unique identifier of the task
DestinationLinkA link to destination where task was uploaded
DestinationStatusThis is the status of your live transcoding task.
It can be one of these statuses: Open, Live, Stopped