JSON Configuration Guide for Advanced Settings

This JSON schema defines various settings for ad injection (Ad Tech) and audio streaming (Playout & Processing).

Note:

For more details, see the documentation for ad-specific parameters and audio-related parameters.

Introduction

The Advanced Settings allow for detailed configuration of our streaming services. This JSON schema defines all available settings that developers can use.

With this schema, you can:

✔️ Validate inputs – to prevent errors ✔️ Generate forms or configuration files ✔️ Efficiently integrate with the API

Download the JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "ad_instream_opener": {
      "type": "array",
      "title": "Instream Ads Opener URLs",
      "description": "URLs for instream ad openers, if more than one are provided, one is picked randomly",
      "items": {
        "type": "string",
        "examples": [
          "https://streamabc-audio-content.s3.eu-central-1.amazonaws.com/sunshinelive/werbetrenner-ssl-3.wav"
        ]
      }
    },
    "ad_instream_closer": {
      "type": "array",
      "title": "Instream Ads Closer URLs",
      "description": "URLs for instream ad openers, if more than one are provided, one is picked randomly",
      "items": {
        "type": "string",
        "examples": [
          "https://streamabc-audio-content.s3.eu-central-1.amazonaws.com/sunshinelive/werbetrenner-ssl-3.wav"
        ]
      }
    },
    "ad_force_preroll_opener": {
      "type": "string",
      "title": "Force Playing Preroll Opener",
      "enum": ["true", "false", ""],
      "description": "Force playing an opener even if no preroll ad is played, boolean string, provide true or false as string",
      "examples": ["true", "false"]
    },
    "ad_force_preroll_closer": {
      "type": "string",
      "title": "Force Playing Preroll Closer",
      "enum": ["true", "false", ""],
      "description": "Force playing a closer even if no preroll ad is played, boolean string, provide true or false as string",
      "examples": ["true", "false"]
    },
    "ad_preroll_opener": {
      "type": "array",
      "title": "Preroll Ads Opener URLs",
      "description": "URLs for preroll ad openers, if more than one are provided, one is picked randomly",
      "items": {
        "type": "string"
      }
    },
    "ad_preroll_closer": {
      "type": "array",
      "title": "Preroll Ads Closer URLs",
      "description": "URLs for preroll ad closers, if more than one are provided, one is picked randomly",
      "items": {
        "type": "string"
      }
    },
    "target_volume_db": {
      "type": "number",
      "description": "Target volume in dB for the stream, all ads will be normalized to this volume",
      "example": -6
    },
    "ad_duration_max": {
      "type": "integer",
      "description": "The maximum duration of ads in seconds for a session before no further ads are played"
    },
    "timeshift": {
      "type": "integer",
      "readOnly": true,
      "description": "NOT IMPLEMENTED"
    },
    "username": {
      "type": "string",
      "description": "Protect a stream with username and password, provide username here"
    },
    "password": {
      "type": "string",
      "description": "Protect a stream with username and password, provide password here"
    },
    "protected": {
      "type": "string",
      "enum": ["true", "false", ""],
      "description": "Protect a stream, provide true or false as string"
    },
    "grace_time": {
      "type": "integer",
      "description": "Time in seconds after an instream ad is played before the next ad is requested",
      "example": 1800
    },
    "grace_time_preroll": {
      "type": "integer",
      "description": "Time in seconds after an preroll ad is played before the next ad is requested",
      "example": 900
    },
    "grace_time_reconnect": {
      "type": "integer",
      "description": "Time in seconds to detect reconnects and not play preroll ads",
      "example": 30
    },
    "reconnect_error_noads": {
      "type": "boolean",
      "description": "Don't play ads if there had been errors detecting a reconnect. It needs a unique listener id provided by the player to work."
    },
    "capping": {
      "type": "integer",
      "description": "Time in seconds between reconnects to suppress preroll ads. It needs a unique listener id provided by the player to work.",
      "example": 900
    },
    "burst": {
      "type": "integer",
      "description": "Send this much seconds of the stream on the beginning of the connection to the player as once. This helps filling the client buffer."
    },
    "adinjection": {
      "type": "string",
      "description": "Fine tune the ad injection mode. One of insert overlay replace replace_delay replace_inventory",
      "examples": ["replace_delay", "replace_inventory"]
    },
    "drift_end": {
      "type": "number",
      "description": "Value in milliseconds to fine tune the end trigger for replacement. Can be negative or positive and moves the trigger point in time."
    },
    "geo_allow_countries": {
      "type": "array",
      "description": "Country codes that are allow to access the stream. If set, any listeners from other countries get blocked",
      "items": {
        "type": "string",
        "examples": ["DE", "AT"]
      }
    },
    "geo_disallow_countries": {
      "type": "array",
      "description": "Country codes that are not allowed to access the stream. If set, any listeners from these countries get blocked",
      "items": {
        "type": "string",
        "examples": ["GB"]
      }
    },
    "geo_fallback": {
      "type": "string",
      "description": "URL to a fallback stream that is played if the listener is blocked by geo restrictions",
      "example": "https://api.streamabc.net/audiolibrary/file/content/sunshinelive/geo/SSL_UKStreamHinweis.mp3"
    },
    "geo_active_hours": {
      "type": "array",
      "description": "List of hours when geo restrictions are active.",
      "items": {
        "type": "integer",
        "examples": ["20", "21"]
      }
    },
    "log_metadata": {
      "type": "boolean",
      "readOnly": true,
      "description": "INTERNAL USE ONLY: log all metadata events"
    },
    "hls_metadata": {
      "type": "boolean",
      "description": "EXPERIMENTAL: add metadata ID3 frames to HLS stream"
    },
    "adaptive_streaming": {
      "type": "boolean",
      "description": "Switch to lower bitrates in case of reconnects. Needs a unique listener id provided by the player"
    },
    "enhanced_parser": {
      "type": "boolean",
      "readOnly": true,
      "description": "INTERNAL USE ONLY: use a different frame parser"
    },
    "trigger_beep_end": {
      "type": "boolean",
      "description": "The end of the beep triggers the ad injection instead of the start of the beep"
    },
    "blocked_agents": {
      "type": "string",
      "description": "Regular expression of user agents that are blocked and don't get access to the stream",
      "example": "Current.*"
    },
    "blocked_aggregators": {
      "type": "array",
      "description": "List of aggregator names that are blocked and don't get access to the stream. Needs a qualified aggregator value provided by the stream url",
      "items": {
        "type": "string",
        "examples": ["tunein", "radiode"]
      }
    },
    "block_anonymous": {
      "type": "boolean",
      "description": "Block listeners of connections without a qualified aggregator value. Attention, this can affect a lot of listeners."
    },
    "blocked_fallback": {
      "type": "string",
      "description": "URL to an audio file that is played whenever a listener is blocked"
    },
    "no_ad_parameter": {
      "type": "string",
      "description": "Value fo the URL query string parameter \"context\" that disables ads for the listener",
      "example": "5d50ajGfpU"
    },
    "adproxy_enabled": {
      "type": "boolean",
      "description": "Enable the use of our Adproxy solution"
    },
    "events_disabled": {
      "type": "boolean",
      "readOnly": true,
      "description": "INTERNAL USE ONLY: disable all events"
    },
    "rmsi_user_profiles": {
      "type": "boolean",
      "description": "Use RMX to get user profiles for ad targeting"
    },
    "companionad_aggregators": {
      "type": "array",
      "description": "Aggregator values for requesting companion ads.",
      "items": {
        "type": "string"
      }
    },
    "detailed_adlogs": {
      "type": "boolean",
      "readOnly": true,
      "description": "INTERNAL USE ONLY: log all ad events"
    },
    "use_profiles": {
      "type": "boolean",
      "description": "EXPERIMENTAL: Use the provided profile_id and load all streamurl values from our profiles service. Needs changes on player side."
    },
    "request_gracetime": {
      "type": "boolean",
      "description": "Request ad servers even if affected by grace time but discard potentially ads. This helps keeping inventory high."
    },
    "adserver_params": {
      "type": "object",
      "description": "Additional parameters for the ad server request",
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "required": [],
  "additionalProperties": false
}

Using the JSON Schema

• The schema can be used in code editors such as Visual Studio Code for automatic validation

• It is compatible with many API testing tools

• If you use form generators, you can import this schema directly