Video Streams

Overview

The Streams service enables you to create and manage live video streams with professional features including low-latency delivery (±4 seconds), DVR functionality, automatic recording, and real-time HTML overlays.

Stream Object

The Stream object contains all configuration and status information for a live stream.

int64

Stream ID

name

string

required

Stream name. Often used as a human-readable identifier.Examples: “Conference in July”, “Stream #10003”, “Open-Air Camera #31 Backstage”

active

bool

Stream on/off switch. When false, PULL is deactivated and PUSH returns an error.

live

bool

Whether the main server is currently receiving and transcoding the stream

backup_live

bool

Whether the backup server is currently receiving the stream (PUSH method only)

pull

bool

true: Stream is received by PULL method from external server
false: Stream is received by PUSH method from encoder/OBS/mobile app

push_url

string

URL to PUSH stream using RTMP/RTMPS protocols. Change “rtmp://” to “rtmps://” for encrypted connection.

push_url_srt

string

URL to PUSH stream using SRT protocol for low-latency over unreliable networks

push_url_whip

string

URL to PUSH WebRTC stream using WHIP protocol for browser-based streaming

backup_push_url

string

Backup RTMP/RTMPS URL for geographic redundancy

backup_push_url_srt

string

Backup SRT URL for geographic redundancy

uri

string

URL to pull stream from (PULL method only). Can specify multiple addresses separated by space for round-robin backup.

hls_cmaf_url

string

HLS output URL with CMAF chunks (.m3u8). Recommended for all HLS streams. Supports low-latency (±5 sec default, ±3 sec available).

hls_mpegts_url

string

Legacy HLS output with MPEG-TS chunks (.ts). For compatibility with legacy devices. Does not support low-latency.

dash_url

string

MPEG-DASH output URL (.mpd). Supports low-latency (±4 sec default, ±2 sec available).

iframe_url

string

Built-in HTML web player URL. Can be embedded in iframe on your website.

dvr_enabled

bool

Whether DVR (rewind) functionality is enabled

dvr_duration

int64

DVR window duration in seconds. Range: [30…14400]. Maximum 4 hours.

auto_record

bool

Enables automatic recording when stream starts. Recordings are saved to video hosting.

record_type

string

Recording source:

origin: Record original RTMP/SRT source
transcoded: Record output with overlays and effects

recording_duration

float64

Current recording duration in seconds (when recording is active)

projection

string

360° visualization mode:

regular: Normal flat stream
vr360: 360° mode
vr180: 180° mode
vr360tb: 3D 360° Top-Bottom

html_overlay

bool

Enable real-time HTML overlay widgets on stream

html_overlays

array

Array of HTML overlay widgets configuration

transcoded_qualities

array

List of qualities the stream is being transcoded to

transcoding_speed

float64

Transcoding speed ratio. Should be 1.0 for real-time. Lower values indicate delivery issues.

screenshot

string

URL to latest screenshot (updated every 10 seconds while live). JPEG format, 1080px wide.

Create Stream

Create a new live stream entity for broadcasting.

stream.go

stream, err := client.Streaming.Streams.New(context.TODO(), streaming.StreamNewParams{
    Name:         "Conference 2024",
    Active:       gcore.Bool(true),
    Pull:         gcore.Bool(false), // PUSH mode
    DvrEnabled:   gcore.Bool(true),
    DvrDuration:  gcore.Int64(3600), // 1 hour
    AutoRecord:   gcore.Bool(true),
    RecordType:   gcore.String("transcoded"),
})

name

string

required

Stream name for identification

active

bool

Enable stream processing. Default: true

pull

bool

true: PULL stream from external server (requires uri)
false: PUSH stream to our servers (default)

uri

string

URL to pull stream from (required if pull=true). Can specify multiple URLs separated by space.

dvr_enabled

bool

Enable DVR functionality. Default: false

dvr_duration

int64

DVR window in seconds. Range: 30-14400 (4 hours). Default: 3600

auto_record

bool

Automatically start recording when stream goes live. Default: false

record_type

string

Recording source: origin or transcoded. Default: origin

projection

string

360° mode: regular, vr360, vr180, vr360tb. Default: regular

html_overlay

bool

Enable HTML overlay widgets. Default: false

quality_set_id

int64

Custom quality set ID for transcoding

client_user_id

int64

Custom user ID in your system

client_entity_data

string

Custom metadata (JSON or any format)

Update Stream

Update stream configuration. All parameters are optional.

stream.go

stream, err := client.Streaming.Streams.Update(
    context.TODO(),
    streamID,
    streaming.StreamUpdateParams{
        Stream: streaming.StreamUpdateParamsStream{
            Name:       "Updated Conference Name",
            Active:     gcore.Bool(true),
            DvrEnabled: gcore.Bool(false),
        },
    },
)

Get Stream

Retrieve stream details including current status and URLs.

stream.go

stream, err := client.Streaming.Streams.Get(context.TODO(), streamID)

if stream.Live {
    fmt.Printf("Stream is live! HLS URL: %s\n", stream.HlsCmafURL)
    fmt.Printf("Player URL: %s\n", stream.IframeURL)
}

List Streams

Retrieve a paginated list of all streams.

stream.go

page, err := client.Streaming.Streams.List(context.TODO(), streaming.StreamListParams{
    Page: gcore.Int64(1),
})

for _, stream := range page.Items {
    fmt.Printf("%d: %s (live: %v)\n", stream.ID, stream.Name, stream.Live)
}

Delete Stream

Delete a live stream. Associated recordings remain as independent video entities.

stream.go

err := client.Streaming.Streams.Delete(context.TODO(), streamID)

Consider using active: false instead of deleting if you want to temporarily disable the stream.

Start Recording

Manually start recording a live stream. Stream must be live.

stream.go

response, err := client.Streaming.Streams.StartRecording(context.TODO(), streamID)

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Recording started for stream %d\n", response.Data.Stream.ID)

Recording takes ±3-7 seconds to initialize. Check the recording and recording_duration fields to confirm recording status.

Stop Recording

Stop recording and save the video.

stream.go

video, err := client.Streaming.Streams.StopRecording(context.TODO(), streamID)

if err != nil {
    log.Fatal(err)
}

if video != nil {
    fmt.Printf("Recording saved as video %d: %s\n", video.ID, video.Name)
}

video

Video

The created video entity from the recording. Returns empty if no recording was active.

Clear DVR

Clear the DVR buffer for a stream.

stream.go

err := client.Streaming.Streams.ClearDvr(context.TODO(), streamID)

Protocol-Specific Examples

RTMP Push Example

stream.go

// Create PUSH stream
stream, err := client.Streaming.Streams.New(context.TODO(), streaming.StreamNewParams{
    Name:   "RTMP Live Stream",
    Active: gcore.Bool(true),
    Pull:   gcore.Bool(false),
})

// Use push_url in OBS or encoder
fmt.Printf("RTMP URL: %s\n", stream.PushURL)
fmt.Printf("RTMPS URL: %s\n", strings.Replace(stream.PushURL, "rtmp://", "rtmps://", 1))

SRT Push Example

stream.go

stream, err := client.Streaming.Streams.New(context.TODO(), streaming.StreamNewParams{
    Name:   "SRT Low-Latency Stream",
    Active: gcore.Bool(true),
})

fmt.Printf("SRT URL: %s\n", stream.PushURLSrt)

Configure SRT latency to 400-2000ms based on your network conditions. Default values may not work well for all scenarios.

HLS Pull Example

stream.go

stream, err := client.Streaming.Streams.New(context.TODO(), streaming.StreamNewParams{
    Name:   "Pulled Stream",
    Active: gcore.Bool(true),
    Pull:   gcore.Bool(true),
    Uri:    gcore.String("https://example.com/stream/playlist.m3u8"),
})

WebRTC WHIP Example

stream.go

stream, err := client.Streaming.Streams.New(context.TODO(), streaming.StreamNewParams{
    Name:   "Browser Stream",
    Active: gcore.Bool(true),
})

// Use push_url_whip with WHIP client in browser
fmt.Printf("WHIP URL: %s\n", stream.PushURLWhip)

WebRTC requires H.264 video and OPUS audio. Both tracks must be present.

Best Practices

Recording Management

Long broadcasts are automatically split into 4-hour videos
If stream drops, recording waits 10 seconds before finalizing
Use auto_record for unattended recording
Choose record_type: transcoded to include overlays

Backup Streams

Use backup URLs for geographic redundancy
System switches to backup after 3-10 seconds of main stream failure
Only one protocol can be active at a time (don’t push RTMP and SRT simultaneously)

DVR Configuration

Set dvr_duration based on your use case (typical: 1-4 hours)
DVR consumes storage proportional to duration
Use ClearDvr() to free buffer space

Performance Monitoring

Check transcoding_speed: should be ~1.0 for real-time
Monitor live and backup_live status
Use screenshot URL for monitoring thumbnails

Overview

Cloud

CDN

DNS

Storage

Streaming

IAM

WAAP

Security

Fastedge

Overview

Stream Object

Create Stream

Update Stream

Get Stream

List Streams

Delete Stream

Start Recording

Stop Recording

Clear DVR

Protocol-Specific Examples

RTMP Push Example

SRT Push Example

HLS Pull Example

WebRTC WHIP Example

Best Practices

Recording Management

Backup Streams

DVR Configuration

Performance Monitoring

Build docs developers (and LLMs) love

Overview

Cloud

CDN

DNS

Storage

Streaming

IAM

WAAP

Security

Fastedge

​Overview

​Stream Object

​Create Stream

​Update Stream

​Get Stream

​List Streams

​Delete Stream

​Start Recording

​Stop Recording

​Clear DVR

​Protocol-Specific Examples

​RTMP Push Example

​SRT Push Example

​HLS Pull Example

​WebRTC WHIP Example

​Best Practices

​Recording Management

​Backup Streams

​DVR Configuration

​Performance Monitoring

Build docs developers (and LLMs) love

Overview

Stream Object

Create Stream

Update Stream

Get Stream

List Streams

Delete Stream

Start Recording

Stop Recording

Clear DVR

Protocol-Specific Examples

RTMP Push Example

SRT Push Example

HLS Pull Example

WebRTC WHIP Example

Best Practices

Recording Management

Backup Streams

DVR Configuration

Performance Monitoring