openapi: 3.0.0
info:
  title: Raskenlund Captioning Module REST API
  version: "1.0"
  description: API for controlling the captioning Wowza modules
  contact:
    email: hello@raskenlund.com
    url: https://raskenlund.com
servers:
  - url: http://{wowza_server}:{api_port}/{vhost_mapping}/v1
    description: local testing endpoint
    variables:
      wowza_server:
        default: localhost
      api_port:
        default: "1935"
      vhost_mapping:
        default: "captions"
paths:
  /version:
    get:
      summary: Query the module version
      operationId: version
      description: Query the module version
      responses:
        '200':
          description: OK
          content:
            application/json:
              example: 1.0.0

  /applications/{applicationName}/streams/{streamName}/caption:
    parameters:
      - in: path
        name: applicationName
        required: true
        schema:
          type: string
          description: wowza application name
          example: live
      - in: path
        name: streamName
        required: true
        schema:
          type: string
          description: the stream name
          example: myStream
      - in: query
        name: trackId
        required: false
        schema:
          type: number
          description: optional track id for CEA608 closed captions
          example: 1

    post:
      summary: Add new captions
      operationId: addCaption
      description: Send in a new set of captions or a single one with optional delay
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptionResponse'
        '400':
          description: Bad request, e.g. json formatting error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptionResponse'

components:
  schemas:
    CaptionRequest:
      type: object
      properties:
        captions:
          type: array
          items:
            $ref: '#/components/schemas/CaptionRequestItem'
        delay:
          type: number
          description: the number of milliseconds to delay the scribe with
          example: 0
    CaptionRequestItem:
      type: object
      properties:
        textData:
          type: string
          required: true
          description: the scribe text itself. Use &lt;br&gt; for line breaks
          example: Oh joy
        language:
          type: string
          required: false
          description: the language of the text, used together with the configured language filtering
          example: en
        wpm:
          type: number
          required: false
          description: the word-per-minute setting specific to a single scribe. If not specified,
            | defaults to the application level setting
          example: 120
    CaptionResponse:
      type: object
      properties:
        success:
          type: boolean
          description: true if the scribe was processed successfully
        message:
          type: string
          description: contains 'OK' if successful, error message otherwise
