# Media Sources

Media sources in AURA are stored in _steering_ and are evaluated and played by _engine_. Each media source object is assigned to a media object.
These media objects are then referred to by other entities, like in `Episode.mediaId`, `Schedule.defaultMediaId`, and `Show.defaultMediaId`.

The following diagram shows the relationship between media and media source objects and contains a subset of their supported fields.

```mermaid
erDiagram
    Media ||--|{ MediaSource : contains
    Media {
        string playoutMode
    }
    MediaSource {
        string type
        string source
    }
```

## Understanding `type` and `source`

The `type` describes **what kind of data** the media source contains, whereas the `source` describes **where the data** can be obtained.

### Available types

AURA currently allows three types: `audio`, `m3u`, and `aura-structuredaudio`.

`audio` is just that: audio data. Basically anything FFMPEG will handle.

`m3u` refers to the common [M3U format](https://en.wikipedia.org/wiki/M3U), which is used for playlists, mostly of local files.

`aura-structuredaudio` is a special format used by AURA to store metadata for uploaded audio files.
It is JSON-encoded, and the only required fields are:

* `path`, which must contain a file system path to an audio file and
* `name`, which must contain the name of the file.

### Available sources

Currently, every `source` in AURA is a URL, usually one that starts with `http://`, `https://`, or `file://`.

Available source URL protocols depend on the `type` of the media source.

For the `audio` type, AURA supports the `file://`, `http://`, `https://`, and `line://` protocols.
`file://` refers to local files on the engine host, `http://` and `https://` refer to audio streams accessible via HTTP,
and `line://` is a special protocol for local line-in devices on the engine host. They are defined
in steering’s radio settings under *Playout* → *Line in channels*.

For the `m3u` type, AURA supports only the `file://` protocol, as this is mostly intended for fallback media.

`aura-structuredaudio` only supports `http://` and `https://`. This type and source combination
is created when audio files are uploaded in the dashboard. In these cases the `source` is the URL of a
[file resource](https://api.aura.radio/battery/#/media-store/media_store_api_v2_files_retrieve) in _battery_.

```{admonition} A common URL pitfall
:class: tip

By definition, URLs expect the hostname after the protocol delimiter (`://`).
This is also true for `file://` and `line://` URLs, even though a hostname doesn’t make sense for AURA in these cases.

Ensure that you add a third slash after the protocol to skip the hostname (`file:///my-file.mp3`, `line:///3`).
```

#### How `file://` URLs are resolved

Note that most of the `file://` sources are interpreted as relative paths to a specific directory on the engine host.
In almost all cases the `type` plays a role in constructing an absolute path because _engine_ has dedicated environment
variables that define base directories for audio files, file uploads, and m3u playlists.

## Examples

These are examples for media sources you will often find in AURA.

An uploaded audio file:

```json
{
  "type": "aura-structuredaudio",
  "source": "https://aura.example.org/battery/media-store/api/v2/2371"
}
```

An audio stream:

```json
{
  "type": "audio",
  "source": "https://cast.example.org/stream.mp3"
}
```

An M3U playlist:

```json
{
  "type": "m3u",
  "source": "file:///my-playlist.m3u"
}
```

A line-in device in the studio:

```json
{
  "type": "audio",
  "source": "line:///2"
}
```