> For the complete documentation index, see [llms.txt](https://audalaxy.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://audalaxy.gitbook.io/docs/json-configuration-guide-advanced-settings/json-configuration-guide-for-advanced-settings.md).

# 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](/docs/json-configurations-for-adtech/json-configurations-for-adtech.md) and [audio-related parameters](/docs/json-configurations-for-audio/json-configurations-for-audio.md).

## 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

```json
{
  "$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_lufs": {
      "type": "number",
      "description": "Target loudness in LUFS for the stream. All ads will be normalized to this loudness",
      "example": -12
    },
    "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