Moment Video Server
Configuration

This section describes syntax of configuration files for Moment VS and lists available configuration parameters.

Main configuration file

By default, the main configuration file is located at /opt/moment/moment.conf
You can specify any other path to the config file using -c command line option when running the server:

/opt/moment/bin/moment -c /path/to/moment.conf

moment.conf file syntax

Configuration file consists of sections. Each section is bounded with curly braces {}. Section can be named or unnamed and can be nested.

MySection {
  InnerSection {
  }
}

Sections contain configuration parameters. It is recommended to put string values of parameters in quotes. Parameters are separated from each other with semicolons or line breaks.

Section {
  MyParameter = "MyValue"
  width = 60; height = 40
}

C preprocessor directives can be used within the configuration file (except #include):

#define VPATH "file:///this/is/a/long/path/"
mod_gst {
  FirstVideo  = VPATH "first_video.ogv"
  SecondVideo = VPATH "second_video.flv"
}

C-style comments can be made:

http {
  // Single-line comment
  /* Multi-line comment */
  #if 0
    #if 0
      Nested multi-line comment.
    #endif
  #endif
}

Network addresses are specified in the form "IP address:Port" or "DNS name:Port". Address or port path can be omitted. Examples of addresses: "momentvideo.org:80", "kernel.org", "192.168.0.1", ":8080".

From now on, configuration parameters are described by full path through all nested sections to a parameter. E.g., parameter my/deep/parameter can be specified in configuration file as follows:

my {
  deep {
    parameter = "value"
  }
}

Primary configuration parameters are listed below.

General configuration parameters

moment/module_path — path to server plugins. Default: /opt/moment/lib/moment-1.0/

moment/num_threads — number of threads to use to serve clients. Default: 0 (clients are served from the main thread).

moment/num_file_threads — number of threads used for video recording. Default: 0 (recording is done from the main thread).

page_pool/min_pages — minimum number of pages of memory to keep allocated by the server (a page is 4 KB in size).

RMTP settings

mod_rtmp module is responsible for serving Flash clients wih RTMPT and RTMPT protocols.

mod_rtmp/enable — enable support for RTMP and RTMPT (yes/no). Default: "yes".

mod_rtmp/rtmp_bind — IP address and TCP port to which the server accepts RTMP connections. Default: ":1935"

mod_rtmp/rtmpt_bind — IP address and TCP port to which the server accepts RTMPT connections. Default: ":8081"

mod_rtmp/rtmpt_session_timeout — RTMPT client session inactivity timeout, in seconds. Client session is closed after the timeout expires. Default: 30 seconds.

mod_rtmp/send_delay — Sending delay for audio messages in milliseconds. Delayed sending (buffering on the server) increases server's performance substantially. E.g., when many clients are connected to the server, CPU load is about 2.5 times less with a delay of 100 milliseconds than with no delay. Default: 50 milliseconds.

mod_rtmp/audio_waits_video — don't send audio messages until the first video message is sent. Default: "no" (send audio without waiting for video).

HTTP settings

Moment VS can accept arbitrary HTTP requests and pass them for handling to modules which subscibe for requests with a certain URI prefix. A separate port is listened to to accept administrator's commands in the form of HTTP requests.

http/http_bind — HTTP bind address. Files served with mod_file will be available from this address as well.

http/admin_bind — HTTP bind address for administrator's commands. Default: ":8082"

http/keepalive_timeout — inactivity timeout for HTTP connections, in seconds. Connections are closed after the timeout expires. Default: 60 seconds.

mod_file module serves relatively small static files (HTML pages, images) to HTTP clients. This module is not meant to serve any video. Configuration parameters for mod_file:

mod_file/enable — enable mod_file (yes/no). Default: "yes".

List of file paths and corresponding URI prefixes is specified with a set of unnamed sections. Each unnamed section contains two parameters:

path — directory from which the files are taken.

prefix — URI prefix to use. E.g., if the files should be available from http://myserver.com/my_files/, then the prefix is "my_files".

Example of mod_file configuration:

mod_file {
  enable = yes
  {
    path = "/opt/moment/myplayer"
    prefix = "moment"
  }
  {
    path = "/opt/moment/mychat"
    prefix = "mychat"
  }
}

Receiving video from Flash clients

Moment VS can receive video from Flash clients and stream it to other clients without extra configuration.

By default, if a client starts streaming video to the server with a certain channel name, then this channel becomes immediately available to other clients for viewing. Automatic channel availability can be disabled by setting moment/publish_all parameter to "no". In this case, video received from Flash clients is available only though plugins which allow that explicitly.

Video grabbing and transcoding

Moment VS uses GStreamer multimedia framework for receiving video from various sources. GStreamer offers rich capabilities for video grabbing, transcoding and transforming video streams on-the-fly, and supports a broad spectre of video formats and codecs.

GStreamer integration is provided by mod_gst module. General settings for mod_gst:

mod_gst/enable — enable mod_gst module. Default: "yes".

mod_gst/no_video_timeout — video source availability timeout, in seconds. If there was no audio or video messages from the source for this period of time, then Moment VS attempts to reconnect to the source. Default: 60 seconds.

mod_gst/send_metadata — generate metadata (onMetaData message) for flv stream format. Default: "no" (onMetaData is not generated).

mod_gst/gst_debug — enable gstreamer debug messages. This can be used to determing causes of errors during video grabbing/transcoding. Default: "off".

From server configuration viewpoint, GStreamer integration means that arbitrary gstreamer pipelines can be used for video processing. Pipelines consist of discrete elements, each of which performs some distinct operation with a video stream. Pipelines are specified using syntax of gst-launch utility. Complete information on gst-launch can be found in system manuals and GStreamer documentation.

Video streams are listed in mod_gst/streams section Each stream is described with an unnamed section. Video source can be specified in one of three ways:

  1. Video stream URI.
  2. Gstreamer pipeline specification.
  3. Playlist.

Common video stream parameters:

name — video stream name. Clients use this name to request the stream from the server.

record_path — path to video recordings. If this parameter is not set, then the stream is not recorded.

URI sources

For the most basic cases of video receiving and trancoding the server offers predefined pipelines. This makes adding new streams easy: all it takes is specifying video resource URI. uri parameter is used to specify an URI. Example:

  {
    // Receving video from an IP camera using RTSP protocol.
    name = "Camera 1"
    uri = "rtsp://91.200.224.242/mpeg4/media.amp"
  }

One may set default width/height and desired compressed video bitrate for video sources specified with an URI. The following parameters have effect for all such sources:

mod_gst/width — width of resulting video streams.

mod_gst/height — height of resulting video streams;

mod_gst/bitrate — bitrate which determines video compression rate, Kbit/sec.

GStreamer pipelines

With gstreamer pipelines one can specify a full set of operations for grabbing, transcoding and transforming video. GStreamer pipelines are chains of elements. Each element performs some distinct operation on a video stream.

Pipelines are specified by strings, which list all pipeline elements and define links between those elements. You can test how a pipeline works separately from the video server using gst-launch command line tool. Pipeline description syntax in the video server's configuration files is the same as the one that gst-launch accepts. Here's how a basic pipeline which displays a color table can be tested with gst-launch:

gst-launch videotestsrc ! autovideosink

This pipeline consists of two elements: videotestsrc element generates a video stream (color table), and autovideosink element displays video in a separate window.

A pipeline must meet some special requirements for Moment VS to be able to use it:

  1. Video processing chain must end with a fakesink element with name "video" (name="video" attribute) and with sync=true attribute.
  2. Audio processing chain must end with a fakesink element with name "audio" (name="audio" attribute) and with sync=true attribute.
  3. Vieo and audio which flows into fakesink elements must be encoded with a codec supported by Moment VS.

Video streams can contain no video or no audio.

To make Moment VS use a gstreamer pipeline for video processing, chain parameter is used in video stream description. Examples of ready-to-use pipelines can be found in the following sections. A list of all available elements for building pipelines and documentation on each element can be obtained with gst-inspect utility.

Playlists

See "Playlists" section for information on how to use playlists.

Receiving video from IP cameras

Video from IP cameras can be received by specifying camera's video stream URI or with a gstreamer pipeline which corresponds to the type of video stream being received. Example of receiving video using RTSP protocol:

  uri = "rtsp://10.1.12.3/mpeg4/media.amp"

Pipeline for receiving MJPEG video over HTTP and transcoding it to h.264:

  chain = "souphttpsrc location=http://192.168.0.1/mjpg/video.mjpg ! \
           multipartdemux ! jpegdec ! ffmpegcolorspace !             \
           x264enc speed-preset=ultrafast bitrate=500 !  \
           fakesink name=video"

Receiving video from local cameras

Under Linux, video from locally connected cameras can be grabbed with "Video for Linux" subsystem. v4lsrc is an element which does this. Example of a pipeline to grab video from a camera:

  chain = "v4l2src device=/dev/video0 ! video/x-raw-yuv,width=320,height=240 ! \
           ffmpegcolorspace ! ffenc_flv ! fakesink name=video"

Receiving video from other sources

Examples of gstreamer pipelines for various video sources follow.

Example 1. Generating a color table and encoding it with Sorenson H.263 video codec.

  {
    chain = "videotestsrc ! ffenc_flv ! fakesink name=video sync=true"
    name = "Example 1"
  }

Example 2. Adding a sound beep encoded with Nellymoser audio codec to video stream from the previous example.

  {
    chain = "videotestsrc ! ffenc_flv ! fakesink name=video sync=true \
             audiotestsrc ! ffenc_nellymoser ! fakesink name=audio sync=true"
    name = "Example 2"
  }

Example 3. Reading video from a file, applying "old tape" effect to it (agingtv), encoding. Raw video format conversion is required for agingtv element, which is done with ffmpegcolorspace element.

  {
    chain = "uridecodebin uri=file:///home/user/video.avi !  \
             ffmpegcolorspace ! agingtv ! ffmpegcolorspace ! \
             ffenc_flv ! fakesink name=video sync=true"
    name = "Example 3"
  }

Example 4. Organizing a screencast. Grabbing video from the screen with a frequency of 15 frames per second and encoding it using Screen Video codec.

  {
    chain =                                                               \
        "ximagesrc use-damage=false do-timestamp=true show-pointer=true ! \
         video/x-raw-rgb,framerate=15/1 !                                 \
         ffmpegcolorspace !                                               \
         ffenc_flashsv ! fakesink name=video"
    name = "Example 4"
  }

Playlists

With playlists you can set up scheduled streaming of video from various sources. A playlist is a linear list of playback elements. Each element contains stream source description (URI, file path, or a gstreamer pipeline) and can be accompanied with "start", "end", "duration", and "seek" attributes.

Playlists are described with separate XML files. The root tag of each file is <playlist>. Playlist elements are represented with <item> tags. Each <item> tag should contain one of the following elements:

uri — video source URI

path — file path

chain — gstreamer pipeline description

<item> tag attributes:

start — playback start time.

end — playback end time.

duration — playback duration. If the value is "full", then video is played util end of file is reached.

seek — playback start position. The video is seeked to this position (time offset) before playback starts.

Allowed time formats: SS, MM:SS, HH:MM:SS (S — seconds, M — minutes, H — hours). Date formats: mm/DD, YY/MM/DD (D — day, m — month, Y — year).

Playlist file example:

<playlist>
  <!-- Playback starts on 27th of November at 12:00 -->
  <item start="11/27 12:00" end="13:00" seek="15">
    <path>/home/user/video/Movie.avi</path>
  </item>
  <item start="13:30" duration="15:00">
    <uri>rtsp://channel_one.com/live/stream.sdp</uri>
  </item>
  <item>
    <chain>
      videotestsrc ! ffenc_flv ! fakesink name=video sync=true
    </chain>
  </item>
</playlist>

playlist parameter with a path to playlist file is used to specify a stream with a playlist:

mod_gst {
  streams {
    {
      name = "Online TV"
      playlist = "/opt/moment/playlist_tv.xml"
    }
  }
}

Moment VS allows to update playlists and change playback positions with administrator's HTTP requests (POST or GET). Playlist update request has the following form:

http://host:port/moment_admin/update_playlist or update_playlist_now/channel_name

update_playlist_now request switches to the new playlist immediately, interrupting playback of an element currently played. update_playlist lets the current element play till its planned end time. Example of an URI for updating a playlist for "my_video" channel:

http://localhost:8082/moment_admin/update_playlist_now/my_video

HTTP request for changing current playback position:

http://host:port/moment_admin/set_position/channel_name/element number or id/time

Example of an URI for seekng to 1 hour and 45 minutes from the start of the first element of "video" channel's playlist:

http://localhost:8082/moment_admin/set_position/video/1/1:45:00

Video recording

Moment VS can record video to a local drive continuosly or by a schedule to .flv files.

To enable continuous recording, set recording_path parameter in stream description section to a path (filename prefix) where recorded files will be put:

  {
    name = "Stream 1"
    uri = "rtsp://91.200.224.242/mpeg4/media.amp"
    record_path = "/home/user/records/stream_1"
  }

Recorded video will be split into several files with a suffix containing date and time when recording started: "_YYYY_mm-DD_HH-MM_SS.flv"

Recording by schedule is requested using a playlist fo the same format as for playback playlists. The main difference of a recording playlist is that instead of specifying video sources in <item> tags, "id" attributes of those tags are set to names of channels to record. Example of a recording playlist:

<playlist>
  <item start="12:00" duration="30" id="channel_one"/>
  <item duration="20" id="channel_two"/>
</playlist>

In the configuration file, recording by schedule can be requested by adding an unnamed subsection into mod_gst/recordings section. Each unnamed subsection has two parameters:

playlist — path to recording playlist file

record_path — path prefix for recorded files

Example:

mod_gst {
  recordings {
    {
      playlist = "recording_playlist.xml"
      record_path = "/home/user/records/my_stream"
    }
  }
}


Back to Contents