mediamtx/apidocs/openapi.yaml

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
        webrtcICEServers2:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              username:
                type: string
              password:
                type: string
        webrtcICEHostNAT1To1IPs:
          type: array
          items:
            type: string
        webrtcICEUDPMuxAddress:
          type: string
        webrtcICETCPMuxAddress:
          type: string

        # srt
        srt:
          type: boolean
        srtAddress:
          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
        rpiCameraHDR:
          type: boolean
        rpiCameraTuningFile:
          type: string
        rpiCameraMode:
          type: string
        rpiCameraFPS:
          type: number
        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
          description: deprecated, replaced by 'ready'
        ready:
          type: boolean
        readyTime:
          type: string
          nullable: true
        tracks:
          type: array
          items:
            type: string
        bytesReceived:
          type: integer
          format: int64
        readers:
          type: array
          items:
            $ref: '#/components/schemas/PathSourceOrReader'

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

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

    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'

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

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

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

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

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

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

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

    SRTConnsList:
      type: object
      properties:
        pageCount:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/SRTConn'

    WebRTCSession:
      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]
        path:
          type: string
        bytesReceived:
          type: integer
          format: int64
        bytesSent:
          type: integer
          format: int64

    WebRTCSessionsList:
      type: object
      properties:
        pageCount:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/WebRTCSession'

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.
        '404':
          description: configuration not found.
        '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.
        '404':
          description: configuration not found.
        '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/hlsmuxers/get/{name}:
    get:
      operationId: hlsMuxersGet
      summary: returns a HLS muxer.
      description: ''
      parameters:
      - name: name
        in: path
        required: true
        description: name of the muxer.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLSMuxer'
        '400':
          description: invalid request.
        '404':
          description: muxer not found.
        '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/paths/get/{name}:
    get:
      operationId: pathsGet
      summary: returns a path.
      description: ''
      parameters:
      - name: name
        in: path
        required: true
        description: name of the path.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Path'
        '400':
          description: invalid request.
        '404':
          description: path not found.
        '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/rtspconns/get/{id}:
    get:
      operationId: rtspConnsGet
      summary: returns a RTSP connection.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTSPConn'
        '400':
          description: invalid request.
        '404':
          description: connection not found.
        '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/get/{id}:
    get:
      operationId: rtspSessionsGet
      summary: returns a RTSP session.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTSPSession'
        '400':
          description: invalid request.
        '404':
          description: session not found.
        '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: ID of the session.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '404':
          description: session not found.
        '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/rtspsconns/get/{id}:
    get:
      operationId: rtspsConnsGet
      summary: returns a RTSPS connection.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTSPConn'
        '400':
          description: invalid request.
        '404':
          description: connection not found.
        '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.
        '404':
          description: session not found.
        '500':
          description: internal server error.

  /v2/rtspssessions/get/{id}:
    get:
      operationId: rtspsSessionsGet
      summary: returns a RTSPS session.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTSPSession'
        '400':
          description: invalid request.
        '404':
          description: session not found.
        '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: ID of the session.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '404':
          description: session not found.
        '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/get/{id}:
    get:
      operationId: rtmpConnectionsGet
      summary: returns a RTMP connection.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTMPConn'
        '400':
          description: invalid request.
        '404':
          description: connection not found.
        '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: ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '404':
          description: session not found.
        '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/get/{id}:
    get:
      operationId: rtmpsConnectionsGet
      summary: returns a RTMPS connection.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTMPConn'
        '400':
          description: invalid request.
        '404':
          description: connection not found.
        '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: ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
        '400':
          description: invalid request.
        '404':
          description: session not found.
        '500':
          description: internal server error.

  /v2/srtconns/list:
    get:
      operationId: srtConnsList
      summary: returns all SRT 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/SRTConnsList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/srtconns/get/{id}:
    get:
      operationId: srtConnsGet
      summary: returns a SRT connection.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the connection.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SRTConn'
        '400':
          description: invalid request.
        '404':
          description: connection not found.
        '500':
          description: internal server error.

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

  /v2/webrtcsessions/list:
    get:
      operationId: webrtcSessionsList
      summary: returns all WebRTC 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/WebRTCSessionsList'
        '400':
          description: invalid request.
        '500':
          description: internal server error.

  /v2/webrtcsessions/get/{id}:
    get:
      operationId: webrtcSessionsGet
      summary: returns a WebRTC session.
      description: ''
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the session.
        schema:
          type: string
      responses:
        '200':
          description: the request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebRTCSession'
        '400':
          description: invalid request.
        '404':
          description: session not found.
        '500':
          description: internal server error.

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