swagger: '2.0'
info:
  title: Zoox BOX Audio APIs
  version: 1.0.0
  description: APIs related to Audio functionality on Tux. These will be used by the Box app.
basePath: /audio
schemes:
  - http
paths:
  '/media/status':
    get:
      tags:
        - media
      summary: Fetches the current state of audio playing
      parameters:
        - in: header
          name: If-None-Match
          description: ETag of previous MediaStatus request.
          type: string
        - in: header
          name: Prefer
          description: |
            Allow client to specify how long to wait for a new MediaStatus. Only
            the `wait` preference is supported. e.g. wait=60 will have the server
            wait for up to 60 seconds for a request whose ETag does not match the one
            passed in If-None-Match header.
            https://tools.ietf.org/html/rfc7240#page-11
          type: string
      produces:
        - application/json
      responses:
        '200':
          schema:
            $ref: '#/definitions/MediaStatus'
          description: The state of media on Tux.
          headers:
            ETag:
              description: |
                Entity tag that allows client to request with If-None-Match
                header. This should be hash of the entire response body.
              type: string
          examples:
            application/json:
              volume:
                level: 30
                mute: false
              currentTrack:
                title: 'Best of Zoox'
                artist: 'Zoox'
                artUri: 'https://tux/93kzc9v32.png'
                durationSeconds: 432
              source: BLUETOOTH
              playState: PLAYING
              trackPositionSeconds: 42
        '304':
          description: The state of media has not changed. i.e. ETag matches If-None-Match.
        '400':
          description: |
            Malformed Prefer header or missing If-None-Match header with a
            proper Prefer header.
        '503':
          description: Unknown error.
    patch:
      tags:
        - media
      summary: Updates state of playing media (e.g. play/pause/volume).
      consumes:
        - application/json
      parameters:
        - in: body
          name: MediaStatusUpdate
          description: Request to change state of media
          required: true
          schema:
            $ref: '#/definitions/MediaStatusUpdate'
      produces:
        - application/json
      responses:
        '200':
          schema:
            $ref: '#/definitions/MediaStatus'
          description: 'Current state of playing media, if any.'
          examples:
            application/json:
              volume:
                level: 30
                mute: false
              currentTrack:
                title: 'Best of Zoox'
                artist: 'Zoox'
                artUri: 'https://tux/93kzc9v32.png'
                durationSeconds: 432
              source: BLUETOOTH
              playState: PAUSED
              trackPositionSeconds: 43
        '503':
          description: Unknown error.
  '/media/controlevent':
    post:
      tags:
        - media
      summary: High-level event to change the currently playing media.
      parameters:
        - in: body
          name: MediaControlEvent
          description: Event to change the state of media.
          required: true
          schema:
            $ref: '#/definitions/MediaControlEvent'
      responses:
        '202':
          description: Event accepted. Poll /media/status for any updates.
        '503':
          description: Unknown error.
  '/image/{id}':
    parameters:
      - in: path
        name: id
        description: Id of the image to retrieve
        required: true
        type: string
    get:
      tags:
        - image
      summary: Returns an image (e.g. album art for a track).
      produces:
        - image/png
        - image/jpeg
        - image/gif
        - image/tiff
        - image/webp
      responses:
        '200':
          schema:
            type: string
            format: binary
          description: Successful operation
        '404':
          description: Image not found
        '503':
          description: Unknown error.
  '/voice/{seatId}':
    parameters:
      - in: path
        name: seatId
        description: Id of the seat in the robot.
        type: integer
        minimum: 1
        required: true
    get:
      tags:
        - voice
      summary: Get voice request status.
      produces:
        - application/json
      responses:
        '200':
          schema:
            $ref: '#/definitions/VoiceRequestStatus'
          description: The current voice request status at this seat.
          examples:
            application/json:
              status: LISTENING
        '503':
          description: Unknown error.
    put:
      tags:
        - voice
      summary: Start/finish a voice request.
      description: Puts the TUX unit in listening mode for a voice request.
      parameters:
        - in: body
          name: VoiceRequestStatus
          description: Request to change state of media
          required: true
          schema:
            $ref: '#/definitions/VoiceRequestStatus'
      responses:
        '200':
          schema:
            $ref: '#/definitions/VoiceRequestStatus'
          description: Voice request initiated.
          examples:
            application/json:
              status: PROCESSING
        '409':
          description: Voice request already in process.
        '503':
          description: Unknown error.
  '/bluetooth':
    get:
      tags:
        - bluetooth
      summary: Get Bluetooth state.
      produces:
        - application/json
      responses:
        '200':
          schema:
            $ref: '#/definitions/BluetoothStatus'
          description: The current state of Bluetooth.
          examples:
            application/json:
              connected: true
              discoverable: false
              connectedDeviceName: Zoox iPhone
        '503':
          description: Unknown error.
    patch:
      tags:
        - bluetooth
      summary: |
        Update the state of the Bluetooth on Tux. i.e. enable pairing.
        Fields that may be updated: 'connected', 'discoverable'
      parameters:
        - in: body
          name: BluetoothStatusUpdate
          description: Request to change state Bluetooth
          required: true
          schema:
            $ref: '#/definitions/BluetoothStatusUpdate'
      responses:
        '200':
          schema:
            $ref: '#/definitions/BluetoothStatus'
          description: Device paired.
          examples:
            application/json:
              connected: true
              discoverable: true
              connectedDeviceName: Zoox iPhone
        '503':
          description: Unknown error.
definitions:
  MediaStatusUpdate:
    type: object
    description: |
      Defines changes/updates wanted by Box to be applied by Tux. Can include any
      number of these fields.
    properties:
      volume:
        $ref: '#/definitions/Volume'
      playState:
        type: string
        enum:
          - PLAYING
          - PAUSED
          - STOPPED
      trackPositionSeconds:
        type: integer
        description: Current position of currentTrack.
      source:
        type: string
        description: Source of the media.
        enum:
          - BLUETOOTH
          - SPOTIFY
  MediaStatus:
    description: |
      The current state of media playing in the vehicle.
    allOf:
      - $ref: '#/definitions/MediaStatusUpdate'
      - type: object
        properties:
          currentTrack:
            $ref: '#/definitions/Track'
    required:
      - volume
      - playState
      - trackPositionSeconds
      - source
  Volume:
    type: object
    properties:
      level:
        type: integer
        minimum: 0
        maximum: 99
        description: Volume level.
      mute:
        type: boolean
        description: True if audio is muted.
    required:
      - level
      - mute
  Track:
    type: object
    properties:
      title:
        type: string
      artUri:
        type: string
        format: uri
        description: Path to album art.
      artist:
        type: string
      durationSeconds:
        type: integer
    required:
      - title
  MediaControlEvent:
    type: object
    properties:
      eventName:
        type: string
        description: The event that happened on Box. e.g. user presses the fast forward button to skip to the next track.
        enum:
          - PLAYLIST_FORWARD
          - PLAYLIST_BACK
    required:
      - eventName
  VoiceRequestStatus:
    type: object
    properties:
      status:
        type: string
        enum:
          - INACTIVE
          - LISTENING
          - PROCESSING
        description: |
          State of a seat`s voice request. Box should set to LISTENING when
          starting a request and to PROCESSING when finished.
    required:
      - status
  BluetoothStatusUpdate:
    type: object
    properties:
      connected:
        type: boolean
        description: Whether Tux is currently connected to a device.
      discoverable:
        type: boolean
        description: Whether Tux is in discovery mode to pair/connect a new device.
  BluetoothStatus:
    allOf:
      - $ref: '#/definitions/BluetoothStatusUpdate'
      - type: object
        properties:
          connectedDeviceName:
            type: string
            description: If connected=true, this is the name of the connected device.
          pairingTimeSeconds:
            type: integer
            description: |
              If discoverable=true, this is the number of seconds which Tux
              will stay discoverable waiting for a new device.
    required:
      - connected
      - discoverable
