openapi: 3.0.2
info:
    title: TTRPG Spotify Syncer
    version: 1.0.0
    description: A brand new API with no content.  Go nuts!
paths:
    /v1/playout:
        summary: Controlling the Playout of media on the primary speaker
        get:
            tags:
                - playout
            responses:
                '200':
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Playout'
                    description: Playout currently being used.
            operationId: getPlayout
            summary: Get current playout state
            description: Get the current state of the playout
        put:
            requestBody:
                description: Playout to apply
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PlayoutSpec'
                required: true
            tags:
                - playout
            responses:
                '200':
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PlayoutSpec'
                    description: The playout spec applied
                '400':
                    description: Playout is missformated.
            operationId: applyPlayout
            summary: Apply a new playout spec
    /v1/speaker/:
        get:
            tags:
                - speaker
            responses:
                '200':
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Speaker'
                    description: List of registerd speakers.
            operationId: listSpeakers
            summary: Get all registered speakers.
            description: Returns a list of speakers currently active.
        put:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Speaker'
                required: true
            tags:
                - speaker
            responses:
                '200':
                    description: Speaker heartbeat.
            operationId: heartbeat
            summary: Heartbeat a speaker
            description: Submit the current state of a Speaker.
    '/v1/speaker/{id}': {}
components:
    schemas:
        PlayoutSpec:
            description: Playout settings for controlling how to playout media
            required:
                - uri
                - strategy
                - speaker
            type: object
            properties:
                uri:
                    description: |-
                        Media URI to playout.
                        Can be one of:
                        spotify:track:6rqhFgbbKwnb9MLmUQDhG6 //track/album/playlist to playout
                        speaker:<id> //speaker to follow
                    type: string
                strategy:
                    description: Strategy to use when playing out media
                    enum:
                        - rollout
                        - fadeout
                        - instant
                    type: string
        SpeakerSpec:
            description: Playout settings for controlling how to playout media
            required:
                - uri
                - strategy
                - speaker
            type: object
            properties:
                uri:
                    description: |-
                        Media URI to playout.
                        Can be one of:
                        spotify:track:6rqhFgbbKwnb9MLmUQDhG6 //track/album/playlist to playout
                        speaker:<id> //speaker to follow
                    type: string
                strategy:
                    description: Strategy to use when playing out media
                    enum:
                        - rollout
                        - fadeout
                        - instant
                        - idle
                        - play
                        - follow
                    type: string
        Speaker:
            description: Individual config of a Speaker
            required:
                - spec
                - id
            type: object
            properties:
                spec:
                    $ref: '#/components/schemas/SpeakerSpec'
                    description: The target spec of a speaker.
                status:
                    $ref: '#/components/schemas/SpeakerStatus'
                    description: Current status of the speaker
                id:
                    description: ID of the speaker
                    type: string
        SpeakerStatus:
            description: The Status of the playout
            required:
                - spec
                - playback_media_uri
                - playback_state
                - playback_timestamp
                - timestamp
            type: object
            properties:
                spec:
                    $ref: '#/components/schemas/SpeakerSpec'
                    description: The spec reported by the speaker
                playback_media_uri:
                    description: The media currently being played.
                    type: string
                playback_state:
                    description: Defines the current state of the playback.
                    enum:
                        - idle
                        - playing
                        - rollout
                        - fadeout
                    type: string
                playback_timestamp:
                    format: float
                    description: The seeker head location in the song.
                    type: number
                timestamp:
                    format: date-time
                    description: Timestamp of the status
                    type: string
        PlayoutStatus:
            description: The Status of the playout
            required:
                - speaker
                - spec
                - timestamp
            type: object
            properties:
                speaker:
                    description: primary speaker reporting the status
                    type: string
                spec:
                    $ref: '#/components/schemas/PlayoutSpec'
                    description: The spec applyed by the speaker
                timestamp:
                    format: date-time
                    description: timestamp of the current status
                    type: string
        Playout:
            description: Playback state and config
            required:
                - spec
            type: object
            properties:
                spec:
                    $ref: '#/components/schemas/PlayoutSpec'
                    description: The specs of the current playout state
                status:
                    $ref: '#/components/schemas/PlayoutStatus'
                    description: The reported status of the primary speaker playout
            example:
                spec:
                    uri: some text
                    strategy: fadeout
                    speaker: some text
                status: {}