Inserting SCTE-35 Splice Insert Signals via API

This guide walks you through using the Visionular API to insert SCTE-35 Splice Insert signals into a live stream. By following this guide, you will learn how to create a SCTE-35 enabled live stream, and insert splice signals to mark ad breaks or program switch points during a live broadcast.

Prerequisites

• A valid Visionular account with API access (AccessKey ID and AccessKey Secret).
• A basic understanding of SCTE-35 and ad insertion workflows. For background on how SCTE-35 markers appear in HLS playlists, see SCTE-35 & SSAI.

Step-by-Step Guide

Step 1: Create a Live Stream with SCTE-35 Support

To use the SCTE-35 Splice Insert feature, you must enable it when creating the live stream by setting scte35_support to true.

API Reference: Create a live stream

Method: POSTURL: /live/v1/live-streams

Request Body:

You can combine scte35_support with other stream creation parameters (e.g., latency_mode, record, policy).

Example Request:

POST /live/v1/live-streams
Host: api.visionular.com
Content-Type: application/json
Authorization: Visionular AccessKeyId={AK}, Signature={SIGN}

{
  "scte35_support": true,
  "latency_mode": "low",
  "policy": ["public"]
}

Example Response:

{
  "code": 0,
  "data": {
    "stream_key": "202501-497b23b4-abcd-xxxx-xxxx-4c65fd3f6edc",
    "status": "idle",
    "reconnect_window": 60,
    "playback_ids": [
      {
        "policy": "public",
        "id": "202501-N2E4ZDlmYzk3YTJhNzM4NTI4ZWFjYTdjODMxODA0ZDc"
      }
    ],
    "type": "normal",
    "max_continuous_duration": 43200,
    "latency_mode": "low",
    "scte35_support": true,
    "id": "202501-NGJmZWM0NTk4NTczMWZkZjhkNmUwNzE1NzVlMWU1OGM",
    "dvr_duration": 1800,
    "created_at": 1735889158
  },
  "message": "success",
  "request_id": "d254a7df-d3dd-4979-a003-02b30637936a"
}

Note the id field — this is your live_stream_id for subsequent steps.

Step 2: Start the Live Stream

Push your live stream via RTMP/RTMPS to the Visionular ingest server using the stream_key from Step 1. The stream must be in active status before you can insert SCTE-35 signals.

You can verify the stream is active by calling the Query a live stream API and checking that status is active.

Step 3: Insert a SCTE-35 Splice Insert Signal

Once the stream is active, you can insert a SCTE-35 Splice Insert signal to mark an ad break or program switch point.

API Reference: Insert a SCTE35 Splice Insert signal

Method: PUTURL: /live/v1/live-streams/{live_stream_id}/scte35-splice-insert

Path Parameters:

Request Body Fields:

Example Request:

PUT /live/v1/live-streams/202501-NGJmZWM0NTk4NTczMWZkZjhkNmUwNzE1NzVlMWU1OGM/scte35-splice-insert
Host: api.visionular.com
Content-Type: application/json
Authorization: Visionular AccessKeyId={AK}, Signature={SIGN}

{
  "scte35_splice_insert": {
    "start_type": "immediate",
    "duration": 30,
    "ad_format": "pip"
  }
}

Example cURL:

curl -X PUT \
  'https://api.visionular.com/live/v1/live-streams/202501-NGJmZWM0NTk4NTczMWZkZjhkNmUwNzE1NzVlMWU1OGM/scte35-splice-insert' \
  -H 'Authorization: Visionular AccessKeyId={AK}, Signature={SIGN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "scte35_splice_insert": {
      "start_type": "immediate",
      "duration": 30,
      "ad_format": "pip"
    }
  }'

Success Response (201 Created):

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "code": 0,
  "message": "success",
  "data": {}
}

Step 4: Verify in HLS Playlist

After a successful insertion, the SCTE-35 markers will appear in the HLS playlist as EXT-X-CUE-OUT / EXT-X-CUE-OUT-CONT / EXT-X-CUE-IN tags. Your SSAI system or player can then react to these markers to insert or replace ad content.

For details on HLS playlist marker format, see SCTE-35 & SSAI.

Ad Format Reference

Error Handling

Limitations

• start_type: Only immediate is supported. PTS-based delayed insertion is not yet available.
• duration: Maximum 57600 seconds (16 hours).
• Stream status: The stream must be active. Idle or disabled streams will return an error.
• Overwrite behavior: Each insertion replaces the entire splice_information_table list, keeping only the latest entry.