Audio Transcoding Plugin

The Transcode plugin provides FFmpeg-based audio/video transcoding capabilities, supporting both rule-based automatic triggering (regex matching on stream publish) and HTTP API manual control for managing transcoding tasks.

Enabling the Plugin

Cargo.toml

features = ["ffmpeg_transcode"]

System Dependencies

The transcoding plugin depends on FFmpeg being installed on the system. Ensure the ffmpeg command is available in PATH, or specify the full path via configuration.

For audio codec support, you may also need to install:

• libopus-dev — Opus codec library (commonly used with WebRTC)
• libfdk-aac-dev — High-quality AAC codec library

# Ubuntu / Debian
sudo apt install ffmpeg libopus-dev libfdk-aac-dev

# CentOS / RHEL
sudo yum install ffmpeg opus-devel fdk-aac-devel

# macOS
brew install ffmpeg opus fdk-aac

Configuration

transcode:
  enable: true
  ffmpeg_path: "ffmpeg"                    # FFmpeg binary path
  mode: "auto"                             # Mode: auto / process
  local_rtmp: "rtmp://127.0.0.1/live"      # Local RTMP address (used as FFmpeg input source)
  onpub:                                    # Auto-transcoding rules (triggered on publish)
    "^live/(.+)$":                          # Regex matching stream path
      outputs:
        - target: "rtmp://cdn.example.com/live/$1"    # Target address (supports regex substitution)
          options:
            video_codec: "libx264"
            audio_codec: "aac"
            video_bitrate: 2000
            audio_bitrate: 128
            resolution: "1280x720"
            frame_rate: 30

Configuration Fields

Field	Type	Default	Description
enable	bool	false	Whether to enable the plugin
mode	string	auto	FFmpeg backend mode
ffmpeg_path	string	ffmpeg	FFmpeg binary path
local_rtmp	string	rtmp://127.0.0.1/live	Local RTMP input address
onpub	map	{}	Auto-transcoding rules

Transcoding Options

Field	Type	Description
video_codec	string	Video encoder (e.g., libx264, libx265, copy)
audio_codec	string	Audio encoder (e.g., aac, libopus, copy)
video_bitrate	int	Video bitrate (kbps)
audio_bitrate	int	Audio bitrate (kbps)
resolution	string	Resolution (e.g., 1280x720)
frame_rate	float	Frame rate

Automatic Transcoding Trigger

When a new stream is published, the Transcode plugin listens for StreamEvent::Created events and matches the stream path against regex rules in onpub. On a successful match, it automatically launches an FFmpeg transcoding process for each outputs entry.

When the source stream is destroyed (StreamEvent::Disposed), the plugin automatically terminates all transcoding tasks associated with that stream.

Typical Scenarios

WebRTC to RTMP Relay

WebRTC streams use Opus audio encoding, but RTMP typically requires AAC. Transcoding rules automatically handle the audio format conversion:

onpub:
  "^webrtc/(.+)$":
    outputs:
      - target: "rtmp://127.0.0.1/live/$1"
        options:
          video_codec: "copy"      # Pass through video without re-encoding
          audio_codec: "aac"       # Opus → AAC
          audio_bitrate: 128

RTMP to Multi-Bitrate Output

Transcode a single RTMP stream into multiple bitrate variants:

onpub:
  "^live/(.+)$":
    outputs:
      - target: "rtmp://127.0.0.1/live/$1_720p"
        options:
          video_codec: "libx264"
          resolution: "1280x720"
          video_bitrate: 2000
          audio_codec: "copy"
      - target: "rtmp://127.0.0.1/live/$1_480p"
        options:
          video_codec: "libx264"
          resolution: "854x480"
          video_bitrate: 1000
          audio_codec: "copy"

CDN Relay

Relay local streams to an external CDN:

onpub:
  "^live/(.+)$":
    outputs:
      - target: "rtmp://cdn-push.example.com/live/$1"
        options:
          video_codec: "copy"
          audio_codec: "copy"

API Endpoints

All endpoints are mounted under the /transcode/api/ route prefix.

List Tasks

GET /transcode/api/list

Returns all currently active transcoding tasks.

Response example:

{
  "code": 0,
  "message": "success",
  "data": {
    "count": 2,
    "jobs": [
      {
        "id": 1,
        "source_path": "live/camera01",
        "input_url": "rtmp://127.0.0.1/live/camera01",
        "target": "rtmp://cdn.example.com/live/camera01"
      }
    ]
  }
}

Manually Start Transcoding

POST /transcode/api/launch
Content-Type: application/json

{
  "source_path": "live/camera01",
  "target": "rtmp://cdn.example.com/live/camera01",
  "options": {
    "video_codec": "libx264",
    "audio_codec": "aac",
    "video_bitrate": 2000,
    "resolution": "1280x720"
  }
}

Response example:

{
  "code": 0,
  "message": "launched",
  "data": { "id": 1 }
}

Stop Transcoding

POST /transcode/api/close
Content-Type: application/json

{
  "id": 1
}

You can also stop all associated tasks by source stream path:

{
  "source_path": "live/camera01"
}

Check if Target Exists

GET /transcode/api/exist?target=rtmp://cdn.example.com/live/camera01

Get Configuration

GET /transcode/api/config

Notes

1. FFmpeg process management: Each transcoding task corresponds to an independent FFmpeg subprocess; the plugin handles process creation and cleanup
2. Resource consumption: Video transcoding (non-copy mode) is CPU-intensive; plan the number of transcoding tasks accordingly
3. local_rtmp configuration: Ensure the engine’s RTMP plugin is enabled and the address matches the local_rtmp setting
4. Target deduplication: Duplicate transcoding tasks will not be created for the same target URL