TranscodeWebhook

TranscodeWebhook을 사용하면 OvenMediaEngine이 로컬 설정(Server.xml)의 OutputProfiles 대신 제어 서버(Control Server) 응답에 포함된 OutputProfiles를 사용할 수 있습니다. 스트림이 생성될 때 OvenMediaEngine은 제어 서버에 OutputProfiles를 요청하며, 이를 통해 각각의 개별 스트림마다 서로 다른 프로파일을 지정할 수 있게 됩니다.

Configuration

<Applications>
	<Application>
		<Name>app</Name>
		<!-- Application type (live/vod) -->
		<Type>live</Type>

		<TranscodeWebhook>
			<Enable>true</Enable>
			<ControlServerUrl>http://example.com/webhook</ControlServerUrl>
			<SecretKey>abc123!@#</SecretKey>
			<Timeout>1500</Timeout>
			<UseLocalProfilesOnConnectionFailure>true</UseLocalProfilesOnConnectionFailure>
			<UseLocalProfilesOnServerDisallow>false</UseLocalProfilesOnServerDisallow>
			<UseLocalProfilesOnErrorResponse>false</UseLocalProfilesOnErrorResponse>
		</TranscodeWebhook>

Enable (required) TranscodeWebhook 설정을 활성화하거나 비활성화할 수 있습니다.

ControlServerUrl (required) 제어 서버(Control Server)의 URL이며, HTTP와 HTTPS를 모두 지원합니다.

SecretKey (optional) 제어 서버의 인증을 통과하는 데 사용되는 비밀 키(Secret Key)입니다. 보안 인증을 통과하기 위해 HTTP 페이로드의 HMAC-SHA1 암호화 값이 HTTP 헤더의 X-OME-Signature에 추가됩니다. 이 키는 해당 값을 생성하는 데 사용됩니다.

Timeout (optional, default: 1500) 제어 서버에 연결할 때 사용되는 타임아웃(Timeout) 값입니다.

UseLocalProfilesOnConnectionFailure(optional, default: true) 제어 서버와의 통신에 실패할 경우 로컬(Local) 설정의 OutputProfiles 사용 여부를 결정합니다. 이 값이 "false"로 설정되어 있으면 제어 서버와의 통신 실패 시 출력(Output) 스트림 생성에 실패하게 됩니다.

UseLocalProfilesOnServerDisallow (optional, default: false) 제어 서버가 200 OK로 응답했지만 "allowed"가 "false"로 설정된 경우 이 정책을 따릅니다.

UseLocalProfilesOnErrorResponse (optional, default: false) 제어 서버가 400 Bad Request, 404 Not Found, 500 Internal Error와 같은 오류 상태 코드로 응답할 때 OvenMediaEngine은 이 정책을 따릅니다.

Protocol

Request (OME → Control Server)

OvenMediaEngine은 다음과 같은 형식으로 제어 서버에 요청을 보냅니다.

POST /configured/target/url/ HTTP/1.1
Content-Length: 1482
Content-Type: application/json
Accept: application/json
X-OME-Signature: f871jd991jj1929jsjd91pqa0amm1
{
  "source": "TCP://192.168.0.220:2216",
  "stream": {
    "name": "stream",
    "virtualHost": "default",
    "application": "app",
    "sourceType": "Rtmp",
    "sourceUrl": "TCP://192.168.0.220:2216",
    "createdTime": "2025-06-05T14:43:54.001+09:00",
    "tracks": [
      {
        "id": 0,
        "name": "Video",
        "type": "Video",
        "video": {
          "bitrate": 10000000,
          "bitrateAvg": 0,
          "bitrateConf": 10000000,
          "bitrateLatest": 21845,
          "bypass": false,
          "codec": "H264",
          "deltaFramesSinceLastKeyFrame": 0,
          "framerate": 30.0,
          "framerateAvg": 0.0,
          "framerateConf": 30.0,
          "framerateLatest": 0.0,
          "hasBframes": false,
          "width": 1280,
          "height": 720,
          "keyFrameInterval": 1.0,
          "keyFrameIntervalAvg": 1.0,
          "keyFrameIntervalConf": 0.0,
          "keyFrameIntervalLatest": 0.0
        }
      },
      {
        "id": 1,
        "name": "Audio",
        "type": "Audio",
        "audio": {
          "bitrate": 160000,
          "bitrateAvg": 0,
          "bitrateConf": 160000,
          "bitrateLatest": 21845,
          "bypass": false,
          "channel": 2,
          "codec": "AAC",
          "samplerate": 48000
        }
      },
      {
        "id": 2,
        "name": "Data",
        "type": "Data"
      }
    ]
  }
}

Response (Control Server → OME)

제어 서버는 해당 스트림에 대한 OutputProfiles를 지정하기 위해 다음 형식으로 응답합니다.

HTTP/1.1 200 OK
Content-Length: 886
Content-Type: application/json
Connection: Closed
{
  "allowed": true,
  "reason": "it will be output to the log file when `allowed` is false",
  "outputProfiles": {
    "outputProfile": [
      {
        "name": "bypass",
        "outputStreamName": "${OriginStreamName}",
        "encodes": {
          "videos": [
            {
              "name": "bypass_video",
              "bypass": "true"
            }
          ],
          "audios": [
            {
              "name": "bypass_audio",
              "bypass": true
            }
          ]
        },
        "playlists": [
          {
            "fileName": "default",
            "name": "default",
            "renditions": [
              {
                "name": "bypass",
                "video": "bypass_video",
                "audio": "bypass_audio"
              }
            ]
          }
        ]
      }
    ]
  }
}

JSON 구조의 outputProfiles 섹션은 Server.xml의 설정을 그대로 반영하며, 아래와 같이 상세한 설정을 지정할 수 있습니다:

"outputProfiles": {
  "hwaccels": {
    "decoder": {
      "enable": false
    },
    "encoder": {
      "enable": false
    }
  },
  "decodes": {
    "threadCount": 2,
    "onlyKeyframes": false
  },
  "outputProfile": [
    {
      "name": "bypass",
      "outputStreamName": "${OriginStreamName}",
      "encodes": {
        "videos": [
          {
            "name": "bypass_video",
            "bypass": "true"
          },
          {
            "name": "video_h264_1080p",
            "codec": "h264",
            "width": 1920,
            "height": 1080,
            "bitrate": 5024000,
            "framerate": 30,
            "keyFrameInterval": 60,
            "bFrames": 0,
            "preset": "faster"
          },
          {
            "name": "video_h264_720p",
            "codec": "h264",
            "width": 1280,
            "height": 720,
            "bitrate": 2024000,
            "framerate": 30,
            "keyFrameInterval": 60,
            "bFrames": 0,
            "preset": "faster"
          }
        ],
        "audios": [
          {
            "name": "aac_audio",
            "codec": "aac",
            "bitrate": 128000,
            "samplerate": 48000,
            "channel": 2,
            "bypassIfMatch": {
              "codec": "eq"
            }
          },
          {
            "name": "opus_audio",
            "codec": "opus",
            "bitrate": 128000,
            "samplerate": 48000,
            "channel": 2,
            "bypassIfMatch": {
              "codec": "eq"
            }
          }
        ],
        "images": [
          {
            "codec": "jpeg",
            "framerate": 1,
            "width": 320,
            "height": 180
          }
        ]
      },
      "playlists": [
        {
          "fileName": "abr",
          "name": "abr",
          "options": {
            "enableTsPackaging": true,
            "webRtcAutoAbr": true,
            "hlsChunklistPathDepth": -1
          },
          "renditions": [
            {
              "name": "1080p_aac",
              "video": "video_h264_1080p",
              "audio": "aac_audio"
            },
            {
              "name": "720p_aac",
              "video": "video_h264_720p",
              "audio": "aac_audio"
            },
            {
              "name": "1080p_opus",
              "video": "video_h264_1080p",
              "audio": "opus_audio"
            },
            {
              "name": "720p_opus",
              "video": "video_h264_720p",
              "audio": "opus_audio"
            }
          ]
        }
      ]
    }
  ]
}