Realtime Getting Started

From OBE Wiki
Jump to: navigation, search

It is now possible to download stable source packages instead of using git: http://www.obe.tv/download

Installing OBE-RT

This guide assumes that Realtime Prerequisites have been completed. It is vital that there are no other versions of ffmpeg/libav, libx264 or libmpegts on the system.

Get the OBE-RT source with the command or download from http://www.obe.tv/:

git clone https://github.com/ob-encoder/obe-rt.git

On RedHat based distributions (RHEL, CentOS, Fedora, etc) you will need to do the following otherwise the correct packages will not be detected:

cd broadcastencoder/ && export PKG_CONFIG_PATH=/usr/lib/pkgconfig

Run the following configure settings and check the correct modules are detected.

./configure --prefix=/usr

Build and install with:

make -j5 && sudo make install

Using OBE-RT

It is strongly recommended to use OBE-RT in GNU Screen. This allows the encoder to be run in the background and accessed when needed. Start GNU screen by typing:

screen

This screen can then by detached by typing Ctrl-A and then 'd'. To reattach the screen type:

screen -r

At the prompt type:

obecli

This will show the obecli shell.

Lowest Latency Encoding

OBE supports very low latency encoding for interviews. This provides an encoder latency of around 80-120ms, depending on the resolution. Low latency needs to be set before probing,

set obe opts system-type=lowestlatency

The vbv-maxrate option described below should not be set when using Lowest Latency encoding. It is strongly recommended to use the intra-refresh option with low-latency.

Probing

First of all an input device needs to be probed.

pal, ntsc, 720p50, 720p59.94, 720p60, 1080i50, 1080i59.94, 1080i60, 1080p23.98,1080p24, 1080p25, 1080p29.97, 1080p30, 1080p50, 1080p59.94, 1080p60

To probe a decklink SDI card issue the following command (replacing XXXXXX) with of the above items

set input decklink
set input opts video-format=XXXXXX
probe input

This will probe the device and output something similar to the following (for 1080i59.94)

Probing device: Decklink card 0. Timeout 20 seconds
..
Detected input streams:
Input-stream-id: 0 - Video: RAW 1920x1080i 30000/1001fps
                     VANC:   CEA-708 Captions
Input-stream-id: 1 - Audio: PCM 8 channels 48kHz

Encoder outputs:
Output-stream-id: 0 - Input-stream-id: 0 - Video: AVC
Output-stream-id: 1 - Input-stream-id: 1 - Audio: RAW - SDI audio pair: 1

OBE refers to a stream by input and output stream ids.

Probing options

For systems with multiple cards the card-idx parameter can be used to choose a card:

set input opts card-idx=0

Cards expose themselves starting from 0

Adding multiple audio streams

An audio stream can be added using the following command:

add stream 2:type=audio

​This produces the following output:

NOTE: output-stream-ids have CHANGED!
Encoder outputs:
Output-stream-id: 0 - Input-stream-id: 0 - Video: AVC
Output-stream-id: 1 - Input-stream-id: 1 - Audio: RAW - SDI audio pair: 1
Output-stream-id: 2 - Input-stream-id: 1 - Audio: RAW - SDI audio pair: 1

The SDI audio pair can be set using the sdi-audio-pair setting described below.

Video Encoding

OBE will have preconfigured encoder settings for the raw video. These settings are based around common broadcast practices such as GOP lengths of 12 for PAL, 15 for NTSC etc. The following mandatory video encoder settings require setting:

set stream opts 0:vbv-maxrate=XXXX,vbv-bufsize=XXXX,bitrate=XXXX,other-options=XXX

vbv-maxrate and bitrate are in kilobits per second and vbv-bufsize is in kilobits. vbv-bufsize is not necessary in lowest latency mode.

AVC Profile

The AVC Profile (baseline, main, high) can be set using the profile option. The default is high.

profile=main

AVC Level

The AVC Level can be set using the level option. The standard level defaults for SD/HD are as described in ETSI TS 101 154.

level=3.2

Horizontal resize

It is also possible to do a horizontal resize to output resolutions such as 1440x1080. This is possible with the width option. Only horizontal resolutions allowed by ETSI TS 101 154 are allowed.

width=1440

Vertical resize is not performed at the encoder in a broadcast chain so this feature will not be supported.

Aspect Ratio

The aspect ratio (default 4:3) of the stream can be set using the aspect-ratio option. Aspect ratios can either be 4:3 or 16:9. There is no need to correct the aspect ratio based on the pixel width (e.g 1440x1080 at 16:9 will have the same aspect ratio as 1920x1080 at 16:9)

aspect-ratio=X:X

Keyframe interval (aka. I-frame interval)

The keyframe interval can be set using the following option. This option is in frames and a vbv-bufsize of the same (or similar) duration should also be set. vbv-bufsize duration is defined as vbv-bufsize divided by vbv-maxrate.

​keyint=XX

The most common keyframe settings are as follows for 25fps (where XXX is the target bitrate set equal to vbv-bufsize):

​keyint=24,vbv-maxrate=XXX,vbv-bufsize=XXX,bitrate=XXX

For 30fps:

​keyint=30,vbv-maxrate=XXX,vbv-bufsize=XXX,bitrate=XXX

Maximum reference frames

Some set top boxes require a restricted number of reference frames below that allowed by the Level in AVC. This can be set using the max-refs parameter.

max-refs=XX

Intra Refresh

Intra Refresh is strongly recommended for use with lowest-latency encoding. The target IRD must be capable of decoding Intra Refresh streams (e.g Sencore MRD 3187B). With intra-refresh mode enabled, keyint determines the number of frames in which a complete intra refresh takes place.

​intra-refresh=1

Audio Encoding

set stream opts 1:bitrate=XXX,format=XXX

The following formats are supported:

mp2   - MPEG I Layer II audio (aka. MUSICAM)
ac3   - ATSC A52/B - AC-3
e-ac3 - Enhanced AC-3
aac   - AAC (default AAC-LC)

Bitrate is in kilobits per second. Common bitrates are 128, 192, 256 or 384 kbps. The bitrate specified must be compliant with the audio codec.

SDI audio pair selection

To select SDI audio pair use the sdi-audio-pair option:

sdi-audio-pair=2

Audio pairs start from 1 as per standard broadcast convention.

Language

The language of the audio can be set using the lang option along with the three letter country code (or any special variants such as NAR or qaa)

lang=eng

Audio Type

The audio type as described in MPEG-2 Systems (ISO/IEC 13818-1) can be set using the audio-type parameter

audio-type=XXXX

The following parameters are allowed:

undefined
clean-effects
hearing-impaired
visual-impaired

AAC Options

AAC encoding has further options:

aac-profile=XXXX,aac-encap=XXXX

aac-profile can be set to the following:

aac-lc
he-aac-v1
he-aac-v2

aac-encap can be set to the following:

adts
latm

DVB strictly speaking requires LATM for encapsulation, however many services use ADTS

MP2 Options

MP2 encoding has further options:

mp2-mode=XXXX

mp2-mode can be set to the following:

stereo
joint-stereo
dual-channel

Mux

The muxer also requires a muxing rate. This is the channel capacity of the stream and is measured in bits per second. This is set using the following command:

set muxer opts ts-muxrate=XXXXX,ts-type=XXXX

The ts-type can be set to the following values:

generic   - Generic (default)
dvb       - DVB
cablelabs - CableLabs
atsc      - ATSC

Constant Bit Rate

The cbr option can be set in order to write stuffing packets. This is not the default and as a result may be the source of errors on TS analysers which assume the input is CBR with stuffing packets.

​cbr=0/1

Transport Stream Id

The transport stream id can be set using the ts-id option:

ts-id=XX

PMT PID

The Program Map Table PID (PMT PID) can be set using the pmt-pid option:

pmt-pid=XXX

Program Number

The Program Number can be set using the program-num option:

program-num=XX

PCR PID

The Program Clock Reference PID (PCR PID) can be set using the pcr-pid option:

pcr-pid=XXX

PCR Period

The PCR Period can be set using the pcr-period option. This value is in milliseconds - the default is the DVB standard of 40ms.

pcr-period=XX

PMT Period

The PMT Period can be set using the pmt-period option. This value is in milliseconds.

pmt-period=XX

Output

Only IP output in OBE is currently supported. UDP is the default and RTP can be chosen using the following command:

set outputs 1
set output opts 0:type=rtp,target=LOCATION

UDP/RTP locations should take the form:

udp://127.0.0.1:1234?ttl=40

As shown, the TTL can be added as an argument. TTL only applies to multicast output.

If one need to output to a different interface than the regular one (only works with multicast targets):

set output opts 0:target=udp://225.5.5.5:5555?ttl=5&miface=eth1

Multiple outputs can be set as follows:

set outputs 2
set output opts 0:type=rtp,target=LOCATION
set output opts 1:type=udp,target=LOCATION

Starting OBE

To start OBE type:

start

Simple Example

Sample start script:

#!/bin/bash

screen -d -m -S obe01 ./obecli
sleep 1
screen -p 0 -S obe01 -X stuff $'set input decklink\012'
screen -p 0 -S obe01 -X stuff $'set input opts video-format=PAL\012'
screen -p 0 -S obe01 -X stuff $'probe input\012'
sleep 2
screen -p 0 -S obe01 -X stuff $'set stream opts 0:vbv-maxrate=4000,vbv-bufsize=2000,bitrate=4000,threads=3,format=avc\012'
screen -p 0 -S obe01 -X stuff $'set stream opts 1:bitrate=224,format=mp2\012'
screen -p 0 -S obe01 -X stuff $'set muxer opts ts-muxrate=5000000,ts-type=generic\012'
screen -p 0 -S obe01 -X stuff $'set outputs 1\012'
screen -p 0 -S obe01 -X stuff $'set output opts 0:target=udp://239.127.1.1:5000?ttl=5\012'
screen -p 0 -S obe01 -X stuff $'start\012'

Advanced Example

A more advanced sample with multiple audios and tweaked to match latency with an Adtec EN-81:

​#!/bin/bash

screen -d -m -S obe01 ./obecli

sleep 1
screen -p 0 -S obe01 -X stuff $'set input decklink\012'
screen -p 0 -S obe01 -X stuff $'set input opts video-format=720p59.94\012' # 720p
screen -p 0 -S obe01 -X stuff $'probe input\012'
sleep 2
screen -p 0 -S obe01 -X stuff $'add stream 2:type=audio\012'
screen -p 0 -S obe01 -X stuff $'set stream opts 1:sdi-audio-pair=1\012'
screen -p 0 -S obe01 -X stuff $'set stream opts 2:sdi-audio-pair=2\012'

screen -p 0 -S obe01 -X stuff $'set stream opts 0:threads=4,format=avc,level=41\012'
screen -p 0 -S obe01 -X stuff $'set stream opts 1:format=mp2\012'
screen -p 0 -S obe01 -X stuff $'set stream opts 2:format=mp2\012'
screen -p 0 -S obe01 -X stuff $'set muxer opts ts-muxrate=21770000,ts-type=dvb,cbr=1\012'

# PID Settings
screen -p 0 -S obe01 -X stuff $'set stream opts 0:pid=512\012' # Video
screen -p 0 -S obe01 -X stuff $'set stream opts 1:pid=4112\012' # Audio1
screen -p 0 -S obe01 -X stuff $'set stream opts 2:pid=4128\012' # Audio2
screen -p 0 -S obe01 -X stuff $'set muxer opts ts-id=1,program-num=1,pmt-pid=256,pcr-pid=512\012' # Transport Stream

# Latency Settings
screen -p 0 -S obe01 -X stuff $'set stream opts 0:lookahead=5,keyint=30,bframes=2\012'

# Bitrate Settings
screen -p 0 -S obe01 -X stuff $'set stream opts 0:vbv-maxrate=20367,vbv-bufsize=20367,bitrate=20367\012' # Video
screen -p 0 -S obe01 -X stuff $'set stream opts 1:bitrate=384\012' # Audio1
screen -p 0 -S obe01 -X stuff $'set stream opts 2:bitrate=384\012' # Audio2

# Multicast Output
screen -p 0 -S obe01 -X stuff $'set outputs 1\012'
screen -p 0 -S obe01 -X stuff $'set output opts 0:target=rtp://239.0.0.4:2000?ttl=5&miface=eth1,type=rtp\012'

# Start
screen -p 0 -S obe01 -X stuff $'start\012'

Help and support

Community support is now handled on the OBE mailing list: https://groups.google.com/forum/?fromgroups=#!forum/obe-discuss or on IRC: https://kiwiirc.com/client/irc.freenode.net/obe