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

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

RMTP settings

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

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.

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:

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

Example of mod_file configuration:

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

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.

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:

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:

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:

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.

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"

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"

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"
  }

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:

<item> tag attributes:

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:

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:

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

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:

Example:

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