Skip to content
Smelter logo Smelter logo Smelter

WHEP server

An output type that provides a WHEP server endpoint. It allows broadcasting a media stream to multiple clients simultaneously.

Smelter exposes WHEP endpoint on port 9000 under /whep/:output_id route. A different port can be configured with SMELTER_WHIP_WHEP_SERVER_PORT.

To connect new output, register it first with register-output request and then establish WHEP connection.

Usage

To use WHEP Output you must register it first. You can do it by sending a request like this:

Example request 

POST: /api/output/:output_id/register
Content-Type: application/json


{
  "type": "whep_server",
  "video": {
    "resolution": { "width": 1280, "height": 720 },
    "encoder": { "type": "ffmpeg_h264" },
    "initial": {
      "root": {
        "type": "view"
      }
    }
  },
  "audio": {
    "encoder": { "type": "opus" },
    "channels": "stereo",
    "initial": {
      "inputs": [{ "input_id": "input_1", "volume": 1 }]
    }
  }
}

See HTTP Routes documentation to learn more about managing outputs.

References

Type definitions 

type WhepServer = {
  type: "whep_server";
  bearer_token?: string;
  video?: VideoOptions;
  audio?: AudioOptions;
}

Properties

bearer_token

Authentication token. If not provided, authentication is not required.

  • Type: string

video

Parameters of a video included in the WHEP stream.

audio

Parameters of an audio included in the WHEP stream.

VideoOptions

Type definitions 

type VideoOptions = {
  resolution: {
    width: u32;
    height: u32;
  };
  send_eos_when?: OutputEndCondition;
  encoder: VideoEncoderOptions;
  initial: { root: Component; };
}

Properties

resolution

Output resolution in pixels.

  • Type: { width: u32; height: u32; }

send_eos_when

Condition for termination of the output stream based on the input streams states. If output includes both audio and video streams, then EOS needs to be sent for every type.

encoder

Video encoder options.

initial

Root of a component tree/scene that should be rendered for the output. Use update_output request to update this value after registration.

  • Type: { root: Component; }

VideoEncoderOptions

Type definitions 

type VideoEncoderOptions =
  | {
      type: "ffmpeg_h264";
      preset?:
        | "ultrafast"
        | "superfast"
        | "veryfast"
        | "faster"
        | "fast"
        | "medium"
        | "slow"
        | "slower"
        | "veryslow"
        | "placebo";
      pixel_format?: "yuv420p" | "yuv422p" | "yuv444p";
      ffmpeg_options?: Map<string, string>;
    }
  | {
      type: "ffmpeg_vp8";
      ffmpeg_options?: Map<string, string>;
    }
  | {
      type: "ffmpeg_vp9";
      pixel_format?: "yuv420p" | "yuv422p" | "yuv444p";
      ffmpeg_options?: Map<string, string>;
    }
  | {
      type: "vulkan_h264";
      bitrate: { average_bitrate: number; max_bitrate: number; } | number;
    };

Properties (type: “ffmpeg_h264”)

preset

Video output encoder preset. Visit FFmpeg docs to learn more.

  • Type: "ultrafast" | "superfast" | "veryfast" | "faster" | "fast" | "medium" | "slow" | "slower" | "veryslow" | "placebo"
  • Default value: fast
  • Supported values:
    • ultrafast
    • superfast
    • veryfast
    • faster
    • fast
    • medium
    • slow
    • slower
    • veryslow
    • placebo

pixel_format

Encoder pixel format

  • Type: "yuv420p" | "yuv422p" | "yuv444p"
  • Default value: yuv420p
  • Supported values:
    • yuv420p
    • yuv422p
    • yuv444p

ffmpeg_options

Raw FFmpeg encoder options. Visit FFmpeg docs to learn more.

  • Type: Map<string, string>

Properties (type: “ffmpeg_vp8”)

ffmpeg_options

Raw FFmpeg encoder options. Visit FFmpeg docs to learn more.

  • Type: Map<string, string>

Properties (type: “ffmpeg_vp9”)

pixel_format

Encoder pixel format

  • Type: "yuv420p" | "yuv422p" | "yuv444p"
  • Default value: yuv420p
  • Supported values:
    • yuv420p
    • yuv422p
    • yuv444p

ffmpeg_options

Raw FFmpeg encoder options. Visit FFmpeg docs to learn more.

  • Type: Map<string, string>

Properties (type: “vulkan_h264”) Required feature: vk-video

Hardware encoder. Requires GPU that supports Vulkan Video encoding.

bitrate

Encoding bitrate. If not provided, bitrate is calculated based on resolution and framerate. For example at 1080p 30 FPS the average bitrate is 5000 kbit/s and max bitrate is 6250 kbit/s.

Type definitions 

type VulkanH264EncoderBitrate = { average_bitrate: number; max_bitrate: number; } | number;

Properties

average_bitrate

Average bitrate measured in bits/second. Encoder will try to keep the bitrate around the provided average, but may temporarily increase it to the provided max bitrate.

max_bitrate

Max bitrate measured in bits/second.

AudioOptions

Type definitions 

type AudioOptions = {
  mixing_strategy?: "sum_clip" | "sum_scale";
  send_eos_when?: OutputEndCondition;
  encoder: AudioEncoderOptions;
  channels?: "mono" | "stereo";
  initial: { inputs: InputAudio[]; };
}

Properties

mixing_strategy

Specifies how audio should be mixed.

  • Type: "sum_clip" | "sum_scale"
  • Default value: "sum_clip"
  • Supported values:
    • sum_clip - First, the input samples are summed. If the result exceeds the i16 PCM range, it is clipped.
    • sum_scale - First, the input samples are summed. If the result exceeds the i16 PCM range, the summed samples are scaled down by a factor to fit within the range.

send_eos_when

Condition for termination of the output stream based on the input streams states. If output includes both audio and video streams, then EOS needs to be sent for every type.

encoder

Audio encoder options.

channels

Channels configuration

  • Type: "mono" | "stereo"
  • Default value: "stereo"
  • Supported values:
    • mono - Mono audio (single channel).
    • stereo - Stereo audio (two channels).

initial

Initial audio mixer configuration for output.

  • Type: { inputs: InputAudio[]; }

AudioEncoderOptions

Type definitions 

type AudioEncoderOptions = {
  type: "opus";
  preset?: "quality" | "voip" | "lowest_latency";
  sample_rate?: u32;
  forward_error_correction?: bool;
  expected_packet_loss?: u32;
}

Properties(type: “opus”)

preset

Audio output encoder preset.

  • Type: "quality" | "voip" | "lowest_latency"
  • Default value: voip
  • Supported values:
    • quality - Recommended for broadcast and high-fidelity applications requiring decoded audio to maintain maximum fidelity to the input signal.
    • voip - Recommended for VoIP and videoconferencing applications, prioritizing listening quality and speech intelligibility.
    • lowest_latency - Recommended only when achieving the lowest possible latency is the highest priority.

sample_rate

Sample rate.

  • Type: u32
  • Default value: 48000
  • Supported values: 8000, 16000, 24000, 48000

forward_error_correction

When enabled, include in-band forward error correction data to protect against packet loss. For more information, visit RFC specification sections 2.1.7 and 4.2.5

  • Type: bool
  • Default value: false

expected_packet_loss

Expected packet loss expressed as a percentage. This value controls how much redundant data is added to counteract packet loss (only when forward error correction is enabled).

  • Type: u32
  • Default value: 0
  • Supported values: 0-100

InputAudio

Type definitions 

type InputAudio = {
  input_id: string;
  volume?: f32;
}

Properties

input_id

ID of an input. It identifies a stream registered using a register input method.

  • Type: string

volume

Input volume in range [0, 2]

  • Type: f32
  • Default value: 1.0
  • Supported values: [0, 2]

OutputEndCondition

This type defines when end of an input stream should trigger end of the output stream. Only one of those fields can be set at the time. Unless specified otherwise the input stream is considered finished/ended when:

  • TCP connection was dropped/closed.
  • RTCP Goodbye packet (BYE) was received.
  • Mp4 track has ended.
  • Input was unregistered already (or never registered).
Type definitions 

type OutputEndCondition = {
  any_of?: string[];
  all_of?: string[];
  any_input?: bool;
  all_inputs?: bool;
}

Properties

any_of

List of the input streams. The output stream will terminate if any stream in the list finishes.

  • Type: string[]

all_of

List of the input streams. The output stream will terminate when all streams in the list finish.

  • Type: string[]

any_input

Terminate the output stream if any of the input streams end, including streams added after the output was registered. Notably, the output stream will not terminate if no inputs were ever connected.

  • Type: bool

all_inputs

Terminate the output stream only when all input streams have finished. Notably, the output stream will terminate if no inputs were ever connected.

  • Type: bool

We use cookies

We use cookies to persist your settings and analyze our traffic. Please select your preferences.

Cookie Preferences