openapi: 3.0.0
info:
  title: AURA Engine API
  description: This is the AURA Engine API.
  contact:
    email: david.trattnig@subsquare.at
  license:
    name: AGPL 3.0
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  version: 1.0.0
externalDocs:
  description: Find more info here
  url: https://gitlab.servus.at/aura/engine-api
servers:
- url: '{protocol}://{api-host}:{port}/api/{version}'
  description: Engine API
  variables:
    protocol:
      default: http
      enum:
      - http
      - https
    api-host:
      description: Hostname or IP for API Host
      default: localhost
    port:
      default: "8008"
    version:
      default: v1
- url: https://virtserver.swaggerhub.com/AURA-Engine/engine-api/1.0.0
  description: SwaggerHub API Auto Mocking
tags:
- name: public
  description: Operations available to the public
- name: internal
  description: Secured calls only
paths:
  /trackservice:
    get:
      tags:
      - public
      summary: List recent tracks in the play-log
      description: |
        Lists the track-service entries for a given page.
      operationId: list_tracks
      parameters:
      - name: from_date
        in: query
        description: Get entries after this timestamp
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
        example: 2020-08-29T09:12:33.001Z
      - name: to_date
        in: query
        description: Get entries before this timestamp
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
        example: 2020-11-29T09:12:55.001Z
      - name: page
        in: query
        description: The number of items to skip before starting to collect the result
          set
        required: false
        style: form
        explode: true
        schema:
          type: integer
      - name: limit
        in: query
        description: The numbers of items to return per page
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 1
          type: integer
          default: 20
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Track'
                x-content-type: application/json
        "400":
          description: bad input parameter
      x-openapi-router-controller: aura_engine_api.rest.controllers.public_controller
  /trackservice/current:
    get:
      tags:
      - public
      summary: Get current track
      description: |
        Retrieves the currently playing track.
      operationId: current_track
      responses:
        "200":
          description: Track currently playing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Track'
        "400":
          description: bad input parameter
      x-openapi-router-controller: aura_engine_api.rest.controllers.public_controller
  /clock:
    get:
      tags:
      - internal
      summary: Get all information to display the studio clock
      description: |
        Retrieves the currently playing timeslot, its playlist and entries plus the next timeslot for being used by the studio clock.
      operationId: clock_info
      responses:
        "200":
          description: Show, Timeslot and Playlist info for the Studio Clock
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClockInfo'
        "400":
          description: bad input parameter
      x-openapi-router-controller: aura_engine_api.rest.controllers.internal_controller
    put:
      tags:
      - internal
      summary: Set current studio clock information such as timeslot info and track-list
        for engine 1 or 2 within the Engine API database.
      description: |
        Set current studio clock information (source, timeslot and planned track-list) and the next timeslot of the given play-out source (engine1, engine2). Please note, the `current_track` and `current_playlogs` information is ignored in the PUT request. It's only dynamically populated in the GET request by reading the most recent playlog. To store current track information use `/playlog` instead. Also note, similar to the `PlayLog` storage endpoint, this information is only stored to the database if a) it is a main node or b) if it's a sync node, and the `engine_source` is the currently active engine.
      operationId: set_clock_info
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClockInfo'
        required: true
      responses:
        "200":
          description: status updated
        "400":
          description: bad input parameter
      x-openapi-router-controller: aura_engine_api.rest.controllers.internal_controller
  /playlog:
    get:
      tags:
      - internal
      summary: List tracks in the play-log since the given timestamp
      description: |
        Get paginated playlog entries for since the given timestamp.
      operationId: list_playlog
      parameters:
      - name: from_date
        in: query
        description: Get entries after this timestamp
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
        example: 2020-08-29T09:12:33.001Z
      - name: to_date
        in: query
        description: Get entries before this timestamp
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
        example: 2020-11-29T09:12:55.001Z
      - name: page
        in: query
        description: The number of items to skip before starting to collect the result
          set
        required: false
        style: form
        explode: true
        schema:
          type: integer
      - name: limit
        in: query
        description: The numbers of items to return per page
        required: false
        style: form
        explode: true
        schema:
          maximum: 200
          minimum: 1
          type: integer
          default: 50
      - name: skip_synced
        in: query
        description: If true only returns items which are in unsynced state on the
          main node
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlayLog'
                x-content-type: application/json
        "400":
          description: bad input parameter
      x-openapi-router-controller: aura_engine_api.rest.controllers.internal_controller
    post:
      tags:
      - internal
      summary: Adds an entry to the playlog
      description: |
        Stores the passed playlog entry in the local database. Also note, similar to the `ClockInfo` storage endpoint, this information is only stored to the database if a) it is a main node or b) if it's a sync node, and the `log_source` is the currently active engine.
      operationId: add_playlog
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlayLog'
        required: true
      responses:
        "200":
          description: Successfully created a new playlog
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
      x-openapi-router-controller: aura_engine_api.rest.controllers.internal_controller
  /playlog/report/{year_month}:
    get:
      tags:
      - internal
      summary: Report for one month
      description: |
        Returns a report for the given month
      operationId: get_report
      parameters:
      - name: year_month
        in: path
        description: Month to create the report for in the format "yyyy_mm"
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        "200":
          description: report matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlayLog'
                x-content-type: application/json
        "400":
          description: bad input parameter
      x-openapi-router-controller: aura_engine_api.rest.controllers.internal_controller
  /source/active:
    get:
      tags:
      - internal
      summary: Get active play-out source (engine1, engine2)
      description: |
        Retrieves the status entry of the currently active source (engine 1, 2 or other source)
      operationId: get_active_source
      responses:
        "200":
          description: source number
          content:
            application/json:
              schema:
                type: integer
                x-content-type: application/json
        "400":
          description: bad input parameter
      x-openapi-router-controller: aura_engine_api.rest.controllers.internal_controller
  /source/active/{number}:
    put:
      tags:
      - internal
      summary: Set active play-out source (engine1, engine2)
      description: |
        Activates one engine and deactivates the other
      operationId: set_active_source
      parameters:
      - name: number
        in: path
        description: Number of the engine
        required: true
        style: simple
        explode: false
        schema:
          maximum: 2
          minimum: 1
          type: integer
      responses:
        "200":
          description: status updated
        "400":
          description: bad input parameter
      x-openapi-router-controller: aura_engine_api.rest.controllers.internal_controller
  /source/health/{number}:
    get:
      tags:
      - internal
      summary: Get most recent health info
      description: |
        Retrieves the most recent health info of the requested engine
      operationId: get_source_health
      parameters:
      - name: number
        in: path
        description: Number of the engine
        required: true
        style: simple
        explode: false
        schema:
          maximum: 2
          minimum: 1
          type: integer
      responses:
        "200":
          description: report matching criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthLog'
        "400":
          description: bad input parameter
      x-openapi-router-controller: aura_engine_api.rest.controllers.internal_controller
    post:
      tags:
      - internal
      summary: Log health info
      description: |
        Logs another health entry for the given engine
      operationId: log_source_health
      parameters:
      - name: number
        in: path
        description: Number of the engine
        required: true
        style: simple
        explode: false
        schema:
          minimum: 1
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HealthLog'
        required: true
      responses:
        "200":
          description: health info logged
        "400":
          description: bad input parameter
      x-openapi-router-controller: aura_engine_api.rest.controllers.internal_controller
components:
  schemas:
    Track:
      required:
      - track_start
      type: object
      properties:
        track_start:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        track_artist:
          type: string
          example: Kyuss
        track_album:
          type: string
          example: '... And the Circus Leaves Town'
        track_title:
          type: string
          example: El Rodeo
        track_duration:
          type: integer
          example: 303
        track_type:
          type: integer
          description: 'Indicates the type: "0" = filesystem, "1" = stream, "2" =
            live or line in'
          example: 2
        track_num:
          type: integer
          example: 11
        playlist_id:
          type: integer
          example: 38
        timeslot_id:
          type: integer
          example: 23
        show_id:
          type: integer
          example: 42
        show_name:
          type: string
          example: Electronic Music from Brazil
      description: Holds all information required to display a public Track Service
        entry. This schema is a sub-set of the `PlayLog` schema.
      example:
        track_album: '... And the Circus Leaves Town'
        show_id: 42
        playlist_id: 38
        track_start: 2020-08-29T09:12:33.001Z
        track_title: El Rodeo
        track_num: 11
        show_name: Electronic Music from Brazil
        track_artist: Kyuss
        timeslot_id: 23
        track_duration: 303
        track_type: 2
    PlayLog:
      required:
      - track_start
      type: object
      properties:
        track_start:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        track_artist:
          type: string
          example: Amon Tobin
        track_album:
          type: string
          example: Bricolage
        track_title:
          type: string
          example: Chomp Samba
        track_duration:
          type: integer
          example: 808
        track_type:
          type: integer
          description: 'Indicates the type: "0" = filesystem, "1" = stream, "2" =
            live or line in'
          example: 2
        track_num:
          type: integer
          example: 11
        playlist_id:
          type: integer
          example: 38
        timeslot_id:
          type: integer
          example: 23
        show_id:
          type: integer
          example: 42
        show_name:
          type: string
          example: Electronic Music from Brazil
        log_source:
          type: integer
          description: From which engine the entry has been logged from e.g. "1" for
            Engine 1 or "2" for Engine 2
          example: 1
        custom_json:
          type: string
          description: A stringified JSON Object allowing the future extension of
            the API with custom fields.
          example: '{ "custom": "Stringified JSON Object" }'
        is_synced:
          type: boolean
          description: For Engine API internal use only - On a main node such as Engine
            1 or 2 this flag indicates if the playlog has been actively synced to
            the sync node. On the sync node in contrast this flag indicates if the
            playlog has been passively synced from one of the main nodes.
          example: true
      description: Holds all information available to the currently playing track.
        This schema is a super-set of the `Track` schema.
      example:
        track_album: Bricolage
        show_id: 42
        track_title: Chomp Samba
        show_name: Electronic Music from Brazil
        track_artist: Amon Tobin
        timeslot_id: 23
        track_type: 2
        is_synced: true
        playlist_id: 38
        track_start: 2020-08-29T09:12:33.001Z
        track_num: 11
        log_source: 1
        track_duration: 808
        custom_json: '{ "custom": "Stringified JSON Object" }'
    HealthLog:
      required:
      - details
      - is_healthy
      - log_time
      type: object
      properties:
        log_time:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        is_healthy:
          type: boolean
          example: true
        details:
          type: string
          description: Stringified JSON Object
          example: '{ "health_info": "{\"engine\": {\"version\": \"0.8.2\", \"status\":
            \"OK\"}, \"soundsystem\": {\"version\": \"Liquidsoap 1.4.3\", \"uptime\":
            \"0d 00h 00m 02s\", \"io\": {\"streams\": {\"stream_0\": {\"enabled\":
            false, \"connected\": \"\"}, \"stream_1\": {\"enabled\": false, \"connected\":
            \"\"}, \"stream_2\": {\"enabled\": false, \"connected\": \"\"}, \"stream_3\":
            {\"enabled\": false, \"connected\": \"\"}, \"stream_4\": {\"enabled\":
            false, \"connected\": \"\"}}, \"recorder\": {\"recorder_0\": {\"enabled\":
            false, \"recording\": false}, \"recorder_1\": {\"enabled\": false, \"recording\":
            false}, \"recorder_2\": {\"enabled\": false, \"recording\": false}, \"recorder_3\":
            {\"enabled\": false, \"recording\": false}, \"recorder_4\": {\"enabled\":
            false, \"recording\": false}}, \"linein\": {\"linein_0\": {\"enabled\":
            true}, \"linein_1\": {\"enabled\": false}, \"linein_2\": {\"enabled\":
            false}, \"linein_3\": {\"enabled\": false}, \"linein_4\": {\"enabled\":
            false}}, \"lineout\": {\"lineout_0\": {\"enabled\": true}, \"lineout_1\":
            {\"enabled\": false}, \"lineout_2\": {\"enabled\": false}, \"lineout_3\":
            {\"enabled\": false}, \"lineout_4\": {\"enabled\": false}}}, \"mixer\":
            {\"in_filesystem_0\": \"ready=false selected=false single=false volume=0%
            remaining=0.00\", \"in_filesystem_1\": \"ready=false selected=false single=false
            volume=0% remaining=0.00\", \"in_http_0\": \"ready=false selected=false
            single=false volume=0% remaining=0.00\", \"in_http_1\": \"ready=false
            selected=false single=false volume=0% remaining=0.00\", \"in_https_0\":
            \"ready=false selected=false single=false volume=0% remaining=0.00\",
            \"in_https_1\": \"ready=false selected=false single=false volume=0% remaining=0.00\",
            \"linein_0\": \"ready=true selected=false single=false volume=0% remaining=(undef)\"},
            \"active\": true}, \"redis\": {\"active\": true}, \"api\": {\"steering\":
            {\"url\": \"http://localhost:8000/api/v1/\", \"available\": true}, \"tank\":
            {\"url\": \"http://localhost:8040/healthz/\", \"available\": true, \"status\":
            {\"auth\": \"OK\", \"store\": \"OK\", \"importer\": \"OK\"}}, \"engine\":
            {\"url\": \"http://localhost:8008/api/v1/ui/\", \"available\": true}},
            \"audio_store\": {\"path\": \"/home/david/Code/aura/tank-store\", \"exists\":
            true, \"has_content\": true}}", "is_healthy": true, "is_synced": false,
            "log_source": 1, "log_time": "2020-10-01T20:22:37" }'
      description: Holds unspecified and extendable health information for both, valid
        and invalid states of the playout engine(s). The data is stored in form of
        stringified JSON.
      example:
        is_healthy: true
        details: '{ "health_info": "{\"engine\": {\"version\": \"0.8.2\", \"status\":
          \"OK\"}, \"soundsystem\": {\"version\": \"Liquidsoap 1.4.3\", \"uptime\":
          \"0d 00h 00m 02s\", \"io\": {\"streams\": {\"stream_0\": {\"enabled\": false,
          \"connected\": \"\"}, \"stream_1\": {\"enabled\": false, \"connected\":
          \"\"}, \"stream_2\": {\"enabled\": false, \"connected\": \"\"}, \"stream_3\":
          {\"enabled\": false, \"connected\": \"\"}, \"stream_4\": {\"enabled\": false,
          \"connected\": \"\"}}, \"recorder\": {\"recorder_0\": {\"enabled\": false,
          \"recording\": false}, \"recorder_1\": {\"enabled\": false, \"recording\":
          false}, \"recorder_2\": {\"enabled\": false, \"recording\": false}, \"recorder_3\":
          {\"enabled\": false, \"recording\": false}, \"recorder_4\": {\"enabled\":
          false, \"recording\": false}}, \"linein\": {\"linein_0\": {\"enabled\":
          true}, \"linein_1\": {\"enabled\": false}, \"linein_2\": {\"enabled\": false},
          \"linein_3\": {\"enabled\": false}, \"linein_4\": {\"enabled\": false}},
          \"lineout\": {\"lineout_0\": {\"enabled\": true}, \"lineout_1\": {\"enabled\":
          false}, \"lineout_2\": {\"enabled\": false}, \"lineout_3\": {\"enabled\":
          false}, \"lineout_4\": {\"enabled\": false}}}, \"mixer\": {\"in_filesystem_0\":
          \"ready=false selected=false single=false volume=0% remaining=0.00\", \"in_filesystem_1\":
          \"ready=false selected=false single=false volume=0% remaining=0.00\", \"in_http_0\":
          \"ready=false selected=false single=false volume=0% remaining=0.00\", \"in_http_1\":
          \"ready=false selected=false single=false volume=0% remaining=0.00\", \"in_https_0\":
          \"ready=false selected=false single=false volume=0% remaining=0.00\", \"in_https_1\":
          \"ready=false selected=false single=false volume=0% remaining=0.00\", \"linein_0\":
          \"ready=true selected=false single=false volume=0% remaining=(undef)\"},
          \"active\": true}, \"redis\": {\"active\": true}, \"api\": {\"steering\":
          {\"url\": \"http://localhost:8000/api/v1/\", \"available\": true}, \"tank\":
          {\"url\": \"http://localhost:8040/healthz/\", \"available\": true, \"status\":
          {\"auth\": \"OK\", \"store\": \"OK\", \"importer\": \"OK\"}}, \"engine\":
          {\"url\": \"http://localhost:8008/api/v1/ui/\", \"available\": true}}, \"audio_store\":
          {\"path\": \"/home/david/Code/aura/tank-store\", \"exists\": true, \"has_content\":
          true}}", "is_healthy": true, "is_synced": false, "log_source": 1, "log_time":
          "2020-10-01T20:22:37" }'
        log_time: 2020-08-29T09:12:33.001Z
    ClockInfo:
      type: object
      properties:
        engine_source:
          type: integer
          example: 1
        current_track:
          $ref: '#/components/schemas/PlayLog'
        current_playlogs:
          type: array
          items:
            $ref: '#/components/schemas/PlayLog'
        planned_playlist:
          $ref: '#/components/schemas/Playlist'
        current_timeslot:
          $ref: '#/components/schemas/Timeslot'
        next_timeslot:
          $ref: '#/components/schemas/Timeslot'
      description: Holds the most recent data required to display the studio clock.
        The field `engine_source` will most likey be the same value as `current_track.log_source`.
        This value represents which engine the record has been logged from. If it
        is not equal for both fields, it most likely indicates an error or an engine
        1 to engine 2 transition process. Another reason is you are using the API
        in some quite futuristic environment, where e.g. an external audio backup
        player is able to log its meta data of what it is playing to the Engine API,
        while the actual `ClockInfo` was logged from an engine instance instead.
      example:
        engine_source: 1
        current_timeslot:
          show_id: 42
          timeslot_end: 2020-08-29T09:12:33.001Z
          playlist_id: 38
          show_name: Electronic Music from Brazil
          fallback_type: 0
          timeslot_start: 2020-08-29T09:12:33.001Z
          timeslot_id: 23
        current_playlogs:
        - null
        - null
        current_track:
          track_album: Bricolage
          show_id: 42
          track_title: Chomp Samba
          show_name: Electronic Music from Brazil
          track_artist: Amon Tobin
          timeslot_id: 23
          track_type: 2
          is_synced: true
          playlist_id: 38
          track_start: 2020-08-29T09:12:33.001Z
          track_num: 11
          log_source: 1
          track_duration: 808
          custom_json: '{ "custom": "Stringified JSON Object" }'
        next_timeslot: null
        planned_playlist:
          entries:
          - track_album: Bricolage
            track_start: 2020-08-29T09:12:33.001Z
            track_title: Chomp Samba
            track_num: 7
            track_artist: Amon Tobin
            track_duration: 808
            track_type: 2
          - track_album: Bricolage
            track_start: 2020-08-29T09:12:33.001Z
            track_title: Chomp Samba
            track_num: 7
            track_artist: Amon Tobin
            track_duration: 808
            track_type: 2
          playlist_id: 38
    Timeslot:
      required:
      - show_name
      type: object
      properties:
        show_name:
          type: string
          example: Electronic Music from Brazil
        show_id:
          type: integer
          example: 42
        timeslot_id:
          type: integer
          example: 23
        timeslot_start:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        timeslot_end:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        playlist_id:
          type: integer
          example: 38
        fallback_type:
          type: integer
          example: 0
      description: Holds data describing some timeslot. Used by `ClockInfo` for the
        studio clock.
      example:
        show_id: 42
        timeslot_end: 2020-08-29T09:12:33.001Z
        playlist_id: 38
        show_name: Electronic Music from Brazil
        fallback_type: 0
        timeslot_start: 2020-08-29T09:12:33.001Z
        timeslot_id: 23
    Playlist:
      required:
      - entries
      type: object
      properties:
        playlist_id:
          type: integer
          example: 38
        entries:
          type: array
          items:
            $ref: '#/components/schemas/PlaylistEntry'
      description: Holds data describing some playlist. Used by `ClockInfo` for the
        studio clock.
      example:
        entries:
        - track_album: Bricolage
          track_start: 2020-08-29T09:12:33.001Z
          track_title: Chomp Samba
          track_num: 7
          track_artist: Amon Tobin
          track_duration: 808
          track_type: 2
        - track_album: Bricolage
          track_start: 2020-08-29T09:12:33.001Z
          track_title: Chomp Samba
          track_num: 7
          track_artist: Amon Tobin
          track_duration: 808
          track_type: 2
        playlist_id: 38
    PlaylistEntry:
      required:
      - track_start
      type: object
      properties:
        track_start:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        track_artist:
          type: string
          example: Amon Tobin
        track_album:
          type: string
          example: Bricolage
        track_title:
          type: string
          example: Chomp Samba
        track_duration:
          type: integer
          example: 808
        track_type:
          type: integer
          example: 2
        track_num:
          type: integer
          example: 7
      description: Holds data describing some playlist entry. Used by `Playlist`,
        indirectly by the studio clock data.
      example:
        track_album: Bricolage
        track_start: 2020-08-29T09:12:33.001Z
        track_title: Chomp Samba
        track_num: 7
        track_artist: Amon Tobin
        track_duration: 808
        track_type: 2
    inline_response_400:
      type: object
      properties:
        message:
          type: string

