openapi: 3.0.0

info:
  version: 1.0.0
  title: MediaMTX API
  description: API of MediaMTX, a server and proxy that supports various protocols.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:9997

security: []

components:
  schemas:
    Conf:
      type: object
      properties:
        # general
        logLevel:
          type: string
        logDestinations:
          type: array
          items:
            type: string
        logFile:
          type: string
        readTimeout:
          type: string
        writeTimeout:
          type: string
        readBufferCount:
          type: integer
        udpMaxPayloadSize:
          type: integer
        externalAuthenticationURL:
          type: string
        api:
          type: boolean
        apiAddress:
          type: string
        metrics:
          type: boolean
        metricsAddress:
          type: string
        pprof:
          type: boolean
        pprofAddress:
          type: string
        runOnConnect:
          type: string
        runOnConnectRestart:
          type: boolean

        # RTSP
        rtspDisable:
          type: boolean
        protocols:
          type: array
          items:
            type: string
        encryption:
          type: string
        rtspAddress:
          type: string
        rtspsAddress:
          type: string
        rtpAddress:
          type: string
        rtcpAddress:
          type: string
        multicastIPRange:
          type: string
        multicastRTPPort:
          type: integer
        multicastRTCPPort:
          type: integer
        serverKey:
          type: string
        serverCert:
          type: string
        authMethods:
          type: array
          items:
            type: string

        # RTMP
        rtmpDisable:
          type: boolean
        rtmpAddress:
          type: string
        rtmpEncryption:
          type: string
        rtmpsAddress:
          type: string
        rtmpServerKey:
          type: string
        rtmpServerCert:
          type: string

        # HLS
        hlsDisable:
          type: boolean
        hlsAddress:
          type: string
        hlsEncryption:
          type: boolean
        hlsServerKey:
          type: string
        hlsServerCert:
          type: string
        hlsAlwaysRemux:
          type: boolean
        hlsVariant:
          type: string
        hlsSegmentCount:
          type: integer
        hlsSegmentDuration:
          type: string
        hlsPartDuration:
          type: string
        hlsSegmentMaxSize:
          type: string
        hlsAllowOrigin:
          type: string
        hlsTrustedProxies:
          type: array
          items:
            type: string
        hlsDirectory:
          type: string

        # WebRTC
        webrtcDisable:
          type: boolean
        webrtcAddress:
          type: string
        webrtcEncryption:
          type: boolean
        webrtcServerKey:
          type: string
        webrtcServerCert:
          type: string
        webrtcAllowOrigin:
          type: string
        webrtcTrustedProxies:
          type: array
          items:
            type: string
        webrtcICEServers:
          type: array
          items:
            type: string
        webrtcICEHostNAT1To1IPs:
          type: array
          items:
            type: string
        webrtcICEUDPMuxAddress:
          type: string
        webrtcICETCPMuxAddress:
          type: string

        # paths
        paths:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PathConf'

    PathConf:
      type: object
      properties:
        source:
          type: string

        # general
        sourceFingerprint:
          type: string
        sourceOnDemand:
          type: boolean
        sourceOnDemandStartTimeout:
          type: string
        sourceOnDemandCloseAfter:
          type: string

        # authentication
        publishUser:
          type: string
        publishPass:
          type: string
        publishIPs:
          type: array
          items:
            type: string
        readUser:
          type: string
        readPass:
          type: string
        readIPs:
          type: array
          items:
            type: string

        # publisher
        disablePublisherOverride:
          type: boolean
        fallback:
          type: string

        # rtsp
        sourceProtocol:
          type: string
        sourceAnyPortEnable:
          type: boolean
        rtspRangeType:
          type: string
        rtspRangeStart:
          type: string

        # redirect
        sourceRedirect:
          type: string

        # raspberry pi camera
        rpiCameraCamID:
          type: integer
        rpiCameraWidth:
          type: integer
        rpiCameraHeight:
          type: integer
        rpiCameraHFlip:
          type: boolean
        rpiCameraVFlip:
          type: boolean
        rpiCameraBrightness:
          type: number
        rpiCameraContrast:
          type: number
        rpiCameraSaturation:
          type: number
        rpiCameraSharpness:
          type: number
        rpiCameraExposure:
          type: string
        rpiCameraAWB:
          type: string
        rpiCameraDenoise:
          type: string
        rpiCameraShutter:
          type: integer
        rpiCameraMetering:
          type: string
        rpiCameraGain:
          type: number
        rpiCameraEV:
          type: number
        rpiCameraROI:
          type: string
        rpiCameraTuningFile:
          type: string
        rpiCameraMode:
          type: string
        rpiCameraFPS:
          type: integer
        rpiCameraIDRPeriod:
          type: integer
        rpiCameraBitrate:
          type: integer
        rpiCameraProfile:
          type: string
        rpiCameraLevel:
          type: string
        rpiCameraAfMode:
          type: string
        rpiCameraAfRange:
          type: string
        rpiCameraAfSpeed:
          type: string
        rpiCameraLensPosition:
          type: number
        rpiCameraAfWindow:
          type: string
        rpiCameraTextOverlayEnable:
          type: boolean
        rpiCameraTextOverlay:
          type: string

        # external commands
        runOnInit:
          type: string
        runOnInitRestart:
          type: boolean
        runOnDemand:
          type: string
        runOnDemandRestart:
          type: boolean
        runOnDemandStartTimeout:
          type: string
        runOnDemandCloseAfter:
          type: string
        runOnReady:
          type: string
        runOnReadyRestart:
          type: boolean
        runOnRead:
          type: string
        runOnReadRestart:
          type: boolean

    Path:
      type: object
      properties:
        name:
          type: string
        confName:
          type: string
        conf:
          $ref: '#/components/schemas/PathConf'
        source:
          $ref: '#/components/schemas/PathSourceOrReader'
        sourceReady:
          type: boolean
        tracks:
          type: array
          items:
            type: string
        bytesReceived:
          type: integer
          format: int64
        readers:
          type: array
          items:
            $ref: '#/components/schemas/PathSourceOrReader'

    PathSourceOrReader:
      type: object
      properties:
        type:
          type: string
          enum:
          - hlsMuxer
          - hlsSource
          - rpiCameraSource
          - rtmpSession
          - rtmpSource
          - rtmpsSession
          - rtspSession
          - rtspSource
          - rtspsSession
          - redirect
          - udpSource
          - webRTCSession
        id:
          type: string

    RTSPConn:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        remoteAddr:
          type: string
        bytesReceived:
          type: integer
          format: int64
        bytesSent:
          type: integer
          format: int64

    RTSPSession:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        remoteAddr:
          type: string
        state:
          type: string
          enum: [idle, read, publish]
        bytesReceived:
          type: integer
          format: int64
        bytesSent:
          type: integer
          format: int64

    RTMPConn:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        remoteAddr:
          type: string
        state:
          type: string
          enum: [idle, read, publish]
        bytesReceived:
          type: integer
          format: int64
        bytesSent:
          type: integer
          format: int64

    HLSMuxer:
      type: object
      properties:
        path:
          type: string
        created:
          type: string
        lastRequest:
          type: string
        bytesSent:
          type: integer
          format: int64

    HLSMuxersList:
      type: object
      properties:
        pageCount:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/HLSMuxer'

    PathsList:
      type: object
      properties:
        pageCount:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Path'

    RTMPConnsList:
      type: object
      properties:
        pageCount:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/RTMPConn'

    RTSPConnsList:
      type: object
      properties:
        pageCount:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/RTSPConn'

    RTSPSessionsList:
      type: object
      properties:
        pageCount:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/RTSPSession'

    WebRTCConn:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        remoteAddr:
          type: string
        peerConnectionEstablished:
          type: boolean
        localCandidate:
          type: string
        remoteCandidate:
          type: string
        state:
          type: string
          enum: [read, publish]
        bytesReceived:
          type: integer
          format: int64
        bytesSent:
          type: integer
          format: int64

    WebRTCConnsList:
      type: object
      properties:
        pageCount:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/WebRTCConn'

paths:
  /v2/config/get:
    get:
      operationId: configGet
      summary: returns the configuration.
      description: ''
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conf'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/config/set:
    post:
      operationId: configSet
      summary: changes the configuration.
      description: all fields are optional. paths can't be edited with this request, use /v2/config/paths/{operation}/{name} to edit them.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Conf'
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/config/paths/add/{name}:
    post:
      operationId: configPathsAdd
      summary: adds the configuration of a path.
      description: all fields are optional.
      parameters:
      - name: name
        in: path
        required: true
        description: the name of the path.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PathConf'
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/config/paths/edit/{name}:
    post:
      operationId: configPathsEdit
      summary: changes the configuration of a path.
      description: all fields are optional.
      parameters:
      - name: name
        in: path
        required: true
        description: the name of the path.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PathConf'
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/config/paths/remove/{name}:
    post:
      operationId: configPathsRemove
      summary: removes the configuration of a path.
      description: ''
      parameters:
      - name: name
        in: path
        required: true
        description: the name of the path.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/hlsmuxers/list:
    get:
      operationId: hlsMuxersList
      summary: returns all HLS muxers.
      description: ''
      parameters:
      - name: page
        in: query
        description: page number.
        schema:
          type: number
          default: 0
      - name: itemsPerPage
        in: query
        description: items per page.
        schema:
          type: number
          default: 100
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLSMuxersList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/paths/list:
    get:
      operationId: pathsList
      summary: returns all paths.
      description: ''
      parameters:
      - name: page
        in: query
        description: page number.
        schema:
          type: number
          default: 0
      - name: itemsPerPage
        in: query
        description: items per page.
        schema:
          type: number
          default: 100
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PathsList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/rtspconns/list:
    get:
      operationId: rtspConnsList
      summary: returns all RTSP connections.
      description: ''
      parameters:
      - name: page
        in: query
        description: page number.
        schema:
          type: number
          default: 0
      - name: itemsPerPage
        in: query
        description: items per page.
        schema:
          type: number
          default: 100
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTSPConnsList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/rtspsessions/list:
    get:
      operationId: rtspSessionsList
      summary: returns all RTSP sessions.
      description: ''
      parameters:
      - name: page
        in: query
        description: page number.
        schema:
          type: number
          default: 0
      - name: itemsPerPage
        in: query
        description: items per page.
        schema:
          type: number
          default: 100
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTSPSessionsList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/rtspsessions/kick/{id}:
    post:
      operationId: rtspSessionsKick
      summary: kicks out a RTSP session from the server.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: the ID of the session.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/rtspsconns/list:
    get:
      operationId: rtspsConnsList
      summary: returns all RTSPS connections.
      description: ''
      parameters:
      - name: page
        in: query
        description: page number.
        schema:
          type: number
          default: 0
      - name: itemsPerPage
        in: query
        description: items per page.
        schema:
          type: number
          default: 100
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTSPConnsList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/rtspssessions/list:
    get:
      operationId: rtspsSessionsList
      summary: returns all RTSPS sessions.
      description: ''
      parameters:
      - name: page
        in: query
        description: page number.
        schema:
          type: number
          default: 0
      - name: itemsPerPage
        in: query
        description: items per page.
        schema:
          type: number
          default: 100
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTSPSessionsList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/rtspssessions/kick/{id}:
    post:
      operationId: rtspsSessionsKick
      summary: kicks out a RTSPS session from the server.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: the ID of the session.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/rtmpconns/list:
    get:
      operationId: rtmpConnsList
      summary: returns all RTMP connections.
      description: ''
      parameters:
      - name: page
        in: query
        description: page number.
        schema:
          type: number
          default: 0
      - name: itemsPerPage
        in: query
        description: items per page.
        schema:
          type: number
          default: 100
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTMPConnsList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/rtmpconns/kick/{id}:
    post:
      operationId: rtmpConnsKick
      summary: kicks out a RTMP connection from the server.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: the ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/rtmpsconns/list:
    get:
      operationId: rtmpsConnsList
      summary: returns all RTMPS connections.
      description: ''
      parameters:
      - name: page
        in: query
        description: page number.
        schema:
          type: number
          default: 0
      - name: itemsPerPage
        in: query
        description: items per page.
        schema:
          type: number
          default: 100
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTMPConnsList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/rtmpsconns/kick/{id}:
    post:
      operationId: rtmpsConnsKick
      summary: kicks out a RTMPS connection from the server.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: the ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/webrtcsessions/list:
    get:
      operationId: webrtcSessionsList
      summary: returns all WebRTC connections.
      description: ''
      parameters:
      - name: page
        in: query
        description: page number.
        schema:
          type: number
          default: 0
      - name: itemsPerPage
        in: query
        description: items per page.
        schema:
          type: number
          default: 100
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebRTCConnsList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/webrtcsessions/kick/{id}:
    post:
      operationId: webrtcSessionsKick
      summary: kicks out a WebRTC connection from the server.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: the ID of the session.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '500':
          description: internal server error.