Using Timeshift Radio

  • Updated on Feb 3, 2025
  • Published on May 25, 2023
  • 3 minute(s) read
Prev Next

Timeshift Radio is currently in limited release to selected publishers.

Timeshift Radio allows a listener to scrub forward and backward through the past few hours of audio (the Timeshift Radio window, which is three hours by default. You can arrange for a custom Timeshift Radio window if you prefer more or less than three hours). This is made possible via a specific HLS playlist URL that lists the recent hours of audio in the .m3u8 playlist file. The audio chunks are saved and served from AWS Cloudfront. The player can then include Timeshift Radio functionalities to move around in those hours of Audio. (For more information, see "Timeshift Radio" in the Triton Digital Streaming Specification.)

The information below applies to Timeshift Radio v3.

"Now Playing" is not supported in Timeshift mode.

Set Up Timeshift Radio

Set up a player as usual and pass the timeShift parameter as part of the play call.

player.play({
    station: TRITONRADIOMUSIC,
    timeShift: true,
  });

  • The player will select a live non-timeshift mount based on the listener's browser and device. All of the normal metrics and advertising operations apply.

  • To use Timeshift Radio, the player needs to call the “seek” method with a value of how much the listener wants to seek.

    • The seek value parameter is in seconds.

    • If the value is negative the player will seek back in time; if it is positive the player will seek forward.

    • The example below shows seeking back one minute in time:
      player.seek(-60);  

  • When a seek is requested, the SDK checks if the player is in live mode, or in Timeshift mode.

    • If this is the first seek event, the player switches from live to Timeshift, where the SDK will connect to the Timeshift mount and jump to the point the listener seeked to.

    • If the player is in Timeshift mode already, seeking forward or backward seeks in the stream to where the listener wants to go.

  • To return to live the player has to call the seekLive() method:
    seekLive();
    This will stop the Timeshift stream and connect again to the live stream.

  • To seek from live the player has to call the seekFromLive() method:
    seekFromLive();
    Seeks back in time the requested number of seconds from the live stream. In this case the number of seconds is always assumed to be negative, so it is not necessary to use " - ". (E.g., both seekFromLive(-1800);   and seekFromLive(1800);  will seek back 1800 seconds.)

Event Listener

The SDK exposes a new event called timeshift-info which you can subscribe to. The data provides general information about the HLS stream. In the example below the variable onTimeshiftInfo is used, but you can use any text string as the variable.

player.addEventListener("timeshift-info", onTimeshiftInfo);
 
function onTimeshiftInfo(e) {
 totalTimeshiftDuration = e.data.totalduration - 10;
 updateTimeshiftSlider({"min": Math.floor(-1 * e.data.totalduration),"max": 0, "label":("-" + formatDate(e.data.totalduration))});
}

Program Anchoring

GetCloudStreamInfo

Use GetCloudStreamInfo to return program information in the timeshift-info event for all the available programs.

For the time being, this feature is limited to the last program received by the Triton Streaming Network. In other words, GetCloudStreamInfo can only return the program that is currently playing. A future release of Timeshift Radio will provide greater program reach.

For example, use:

player.GetCloudStreamInfo("TRITONRADIOMUSIC")

...to return data such as is seen in the example below:

{ 
      "maximumRewindTimeSec": 10800,
      "programs": {
            "name": "program",
            "program_episode_id": "48651-1678715517259",
            "properties": {
                  "cue_id": "23337",
                  "cue_time_start": "1678715517259",
                  "cue_title": "ProgramStart",
                  "program_id": "48651",
                  "program_time_start": "1678715517259",
                  "program_title": "The Lunch Punch with Evie",
                  "stw_cached": "false",
                  "stw_original_type": "stwcue"
            }
      }
}

Example of the timeshift-info event:

function onTimeshiftInfo(e) {
 
 if(e.data.programs){
   let timeshiftPrograms = e.data.programs.map((item)=>{
     let startTimeLabel = new Date(parseInt(item.properties.program_time_start.trim())).toLocaleString('en-US', {  
       hour: 'numeric',
       minute: 'numeric',
       second: 'numeric',
       hour12: false
     });
 
     return {
       "name": item.name,
       "title": item.properties.program_title,
       "startTime": startTimeLabel,
       "programId": item.properties.program_id
       
       }
   });  
}

playProgram

Use playProgram to play the program that was returned with GetCloudStreamInfo

If the returned program's start time was beyond the limit of the Timeshift Radio Window, then playback starts at the limit of that window, not at the beginning of the program. For example, if your Timeshift Radio Window is three hours, and the program started 3.5 hours before GetCloudStreamInfo was used, then playProgram will start playing the program 30 minutes into its episode (i.e., three hours back from the current time).

The playProgram method uses the following parameters:

  • Program ID: The program ID that was returned for the program you want to play.

  • Offset: Set to 0 to start playback from the beginning of the program. Valid range is from 0 to the duration of the program.

  • Station name: The station name. E.g., "TRITONRADIOMUSIC"

Example:

player.playProgram(48651-1678715517259, 0, "TRITONRADIOMUSIC")

Set Up Force Timeshift Mode

The forceTimeShift function causes the SDK to pick the Timeshift mount from the initial connection, and to play in Timeshift mode.

player.play({
    station: TRITONRADIOMUSIC,
    forceTimeShift: true,
  });