Reference General

Reference Manual - General

Updated for Snowmix 0.4.4

This is the reference manual for Snowmix for the commands belonging to the the general commands affecting system wide parameters. See also:

• Reserved Commands overview
• Reference manual for general commands
• Reference manual for command macros
• Reference manual for audio feed commands. See also Audio.
• Reference manual for audio mixer commands. See also Audio.
• Reference manual for audio sink commands. See also Audio.
• Reference manual for feed commands.
• Reference manual for text commands. See also Video Text and Snowmix Tutorials on text.
• Reference manual for image commands.
• Reference manual for shape commands. See the manual page on Shapes.
• Reference manual for placed shapes.
• Reference manual for Cairo Graphics Primitives used in shapes
• Reference manual for virtual feed commands.

Overview

• include - include an ini file or a snowmix library (slib).
• maxplaces - set max number of objects for strings, fonts, texts, images, imageplaces, video feeds, virtual feeds, audio feeds, audio mixers, audio sinks.
• message - write a message to control connection.
• messagef - write a message to control connection and prepend current output frame number.
• monitor - open a monitor window to show mixed video result.
• overlay finish - setting command macro to execute before output.
• overlay pre - setting command macro to execute at frame rate before mixing the system frame.
• png write - write output frame to a png file.
• quit - quit/exit Snowmix.
• require version - check that the version of Snowmix match the required version for the ini file.
• select - select a video feed as the base frame.
• stack - mix (stack) video feeds onto base frame.
• stat - list status and configuration of feeds.
• system control port - sets the control port number.
• system frame rate - sets the frame rate by which Snowmix will produce output frames.
• system geometry - set the size of the (system) video mixer output frame.
• system host allow - control which hosts can establish a control connection.
• system info - list system information.
• system name - set the name of the Snowmix session.
• system output buffers - set the number of frames allocated for output.
• system output delay - delay the output stream a specified number of frames
• system output freeze - freeze video output by outputting the same static frame.
• system output info - list configured settings for output.
• system output mode - sets the video output mode.
• system output reset - reset (close) the output connection.
• system output status - list the status of the output connection.
• system socket - set the mixer's control socket for output to GStreamer shmsrc
• verbose - be verbose to print more information.

include

Name

include - include an ini file or a snowmix library (slib).

Synopsis

include <file name>

Description

The include command includes an ini file from within another ini file. This command should not be used interactively as it potentially can block or delay further audio and or video mixing.

Example

    include ../ini/audio

See also

-

maxplaces

Name

maxplaces - set max number of objects for strings, fonts, texts, images, imageplaces, video feeds, virtual feeds, audio feeds, audio mixers, audio sinks.

Synopsis

maxplaces [(strings | fonts | texts | images | imageplaces | video feeds | virtual feeds | audio feeds | audio mixers | audio sinks) <number>]

Description

The command maxplaces is used to list of set the max number of objects where objects are strings, fonts, texts, images, imageplaces, video feeds, virtual feeds, audio feeds, audio mixers, audio sinks. This command should be placed early in an ini file before any of the objects are referenced. Any reference to the listed objects before this command is used, will render a use of this command later to be ignored for the referenced object. When the command maxplaces is given without any further arguments, the command will list the maxplace value for each object type.

Examples

    maxplaces strings 64

    maxplaces texts 128

The examples configure Snowmix to be able to hold 64 different strings definitions and 128 text placed definitions.

See also

require version

message, messagef

Name

message - write a message to control connection
messagef - write a message to control connection and prepend current output frame number

Synopsis

message <some text>
messagef <some text>

Description

The commands message and messagef write a message to the control and they are intended to be used primarily for debugging. The commands can be used as individual commands or used inside a command macro definition. If the commands are executed as part of executing the command macro set with overlay pre or overlay finish, the commands will be silent and not produce any output. The commands can verify execution of a specific part of a defined command macro.

Example

    command create SomeCommand 
      message executing SomeCommand
      ..
      ..
      ..
      message reached end of SomeCommand
      loop
    command end

    SomeCommand

    command create SomeTclScript.tcl
      snowmix parse "message Tcl script begins\n"
      proc SomeTclProcedure {str} {
        snowmix parse "message $str : SomeTclProcedure was called\n"
        return
      }
      snowmix parse "message Tcl script ends\n"
    command end
    tcl exec SomeTclScript.tcl
    ...
    tcl eval SomeTclProcedure Hello

See also

command create

monitor

Name

monitor - open a monitor window to show mixed video result

Synopsis

monitor [on | off]

Description

The command monitor will open or close a window displaying the resulted mixed video. This command should in most cases not be used over remote connections. Note that the mixer does not produce any mixed video frames, hence no output to the monitor, if there is no consumer of the video mixer. For that to happen, a gstreamer pipeline using shmsink with the right parameters must be operating.

Example

    monitor on

    monitor off

See also

png write

overlay finish

Name

overlay finish - setting command macro to execute before output.

Synopsis

overlay finish <command macro>

Description

The overlay finish command is used to set the command macro to be excuted before the finished mixed frame is to be sent to output. The command macro will be executed for every system frame being mixed as the last thing before the system frame is sent to output. The command macro will not be executed if there is no GStreamer shmsrc connected to Snowmix.

Example

    command create Show
      virtual feed overlay 1 2..4
      text overlay all
      loop
    command end
    overlay finish Show

See also

command create, overlay pre

overlay pre

Name

overlay pre - setting command macro to execute at frame rate before mixing the system frame.

Synopsis

overlay pre <command macro>

Description

The overlay pre command is used to set the command macro to be excuted at frame rate anything else. This command macro will always be executed whether or not a GStreamer shmsrc is connected to Snowmix. If Snowmix is late mixing frames, and if the output mode of Snowmix is set to 1 or larger, the command macro will be executed more than once to ensure that the command macro always has been executed the number of times equal to elapsed time in seconds multiplied with the frame rate in frames per second.

Example

    command create preShow
      tcl eval Update pre
      loop
    command end
    overlay pre Show

The above example ensures that the Tcl procedure Update defined elsewhere is called at frame rate with the argument 'pre' before mixing each frame.

See also

command create, overlay pre, output mode

png write

Name

png write - write output frame to a png file

Synopsis

png write <file name>

Description

The command png write will write the mixed video output frame to a file once. Currently this command runs in the main thread. On slow systems (slow cpu or slow disk or both) this may result in a delay in producing mixed output frames which potentially can decrease production quality. If the file written to is a named pipe/fifo it might even block Snowmix completely. The solution in a future version of Snowmix will be to write the png file in a separate thread receiving a copy of the frame to be written via a signal.

Example

    png write /tmp/frame.png

See also

monitor

quit

Name

quit - quit/exit Snowmix

Synopsis

quit

Description

The command quit is the proper way to terminate Snowmix. Using this command, Snowmix will in a proper way de-allocate the portion of shared memory it has allocated. If Snowmix instead is terminated due to Ctrl-C or due to receiving a signal causing it to terminate, allocated shared memory stays allocated. Eventually this may lead to exhausting available shared memory causing Snowmix and/or other applications using shared memory to fail.

Example

    quit

See also

-

require version

Name

require version - check that the version of Snowmix match the required version for the ini file

Synopsis

require version <major 1>.<major 2>.<minor>

Description

The command require version is intended to check that the running version of Snomwix is suitable for the ini file in which the require version command occur. If the required version for Snowmix is not satisfied, Snowmix will exit. The required version of Snowmix is satisfied if the following conditions are met:

    Snowmix major 1 == major 1
    Snowmix major 2 >= major 2
    Snowmix minor 1 >= minor 1

Example

    require version 0.4.0

See also

include

select

Name

select - select a video feed as the base frame

Synopsis

select <feed no>

Description

The command select is intended to set a specific video feed as the base frame. The command clears the stack list set with the command stack and sets the stack list to the specified video feed only. If virtual feeds are used, it will in many cases not make sense to use this command. For the select command to succeed, the video feed specified must have been defined and must have a geometry identical to the system geometry. Otherwise the command will fail and be ignored.

Example

    select 2

    select 0

The given example is identical to executing the command stack 2. The command can be given any time time while Snowmix is running and as many time desired. Video feed 0 is guaranteed to always have the same size as the system geometry.

The commands select and stack and the limitations they impose to the video mixing are deprecated by the introduction of the much more flexible and powerful virtual feeds in Snowmix. However both commands are kept for cases where only a very rudimentary video mixing is needed due to the low overhead of basic video mixing using select and stack.

See also

system geometry, stack, feed commands

stack

Name

stack - mix (stack) video feeds onto base frame

Synopsis

stack [ list | <feed id> [ &ltfeed id> [ ... ]]]

Description

The command stack defines the order by which video feeds are mixed (stacked) onto the base frame. Stacked video feeds are placed and clipped according to how the feeds are defined using the feed commands. The command can be given any time time while Snowmix is running and as many time desired. The first feed id given to any stack command should always be a feed that has the same video geometry as the system video geometry. Video feed 0 is guaranteed to always have the same size as the system geometry.

The commands select and stack and the limitations using video feeds directly have for video mixing are deprecated by the introduction of the much more flexible and powerful virtual feeds in Snowmix. However both commands are kept for cases where only a very rudimentary video mixing is needed due to the low overhead of basic video mixing using select and stack. It is recommended that that Snowmix configurations using virtual feeds includes the command stack 0 to add a black background to every base frame upon which the virtual feeds will be mixed.

Example

    stack 4 1 2 3
    stack 4 2 3 4 1
    stack 0

See also

select, system geometry, feed commands

stat

Name

stat - list status and configuration of feeds

Synopsis

stat

Description

The command stat can be used to list the status and the configuration of video feeds. This command will in a later version be deprecated and replaced by the new commands feed info and feed status in style for what applies for audio feeds.

Example

    stat

    STAT: ID  Name                  State               Mode     Cutout       Size     Offset  Stack Layer
    STAT:  0  <Internal            >  Stalled       Fullscreen     0x0     1024x576      0x0      1:1  0
    STAT:  1  <Feed #1             >  Running           Cutout    32x96     320x192    704x0      1:2  --
    STAT:  2  <Feed #2             >  Running           Cutout    32x96     320x192    704x192    1:2  --
    STAT:  3  <Feed #3             >  Running           Cutout    32x96     320x192    704x384    1:2  --
    STAT:  4  <Feed #4 1024x576    >  Running       Fullscreen   160x0      704x576      0x0      1:1  --
    STAT: --

The example above shows the information listed for a given setup with 4 video feeds running.

See also

system info

system control port

Name

system control port - sets the control port number

Synopsis

system control port <port number>

Description

The command system control port is intended to set the tcp port number that a running Snowmix will listen for incoming control connections. The port number must be less than 65536. Unless Snowmix is run by the user root, the port number must also be greater than 1023. The command will fail if the port specified is in use by another process. Snowmix has no direct limitation on number of incoming control connections other than what the operating system imposes. However it has a limitation on number of pending connections requests set by the definition of MAX_LISTEN_BACKLOG in the snowmix.h file. Using this command more than once is ignored.

Example

    system control port 9999

See also

system geometry, system frame rate, system socket

system frame rate

Name

system frame rate - sets the frame rate by which Snowmix will produce output frames

Synopsis

system frame rate <frames/s>

Description

The command system frame rate sets the rate by which Snowmix will produce mixed video output frames. Valid frame rate is greater than or equal to MIN_SYSTEM_FRAME_RATE and less than or equal to MAX_SYSTEM_FRAME_RATE. Currently MIN_SYSTEM_FRAME_RATE is set to 1 and MAX_SYSTEM_FRAME_RATE is set to 100 in the file controller.h.
Snowmix will at frame rate perform the following tasks in the function output_producer() in the file video_mixer.cpp

• if (overlay pre defined) execute the command set by overlay pre
• update audio feeds
• update audio mixers
• update audio sinks
• executed timed commands if any timed commands overdue for execution
• if (no video output connected (shm)) return
• overlay video feeds set by command select and command stack including clipping and scaling and copy result to base frame
• increment frame counter
• set base frame as paint frame for Cairo Graphics
• if (overlay finish defined) execute the command set by overlay finish
• if (monitor on) output base frame to screen using SDL.
• write out base frame to shared memory

The overlay finish command if existing is expected to draw text, images and virtual feeds onto the base frame using Cairo Graphics and possible OpenGL in later versions.

Example

    system frame rate 25
    system frame rate 23.97

Warning
While it is possible to change the system frame rate while Snowmix is running, it is not advisable to do so. If you need to do so, you may want first to read and understand the code in the loop in the function main_poller() in the file main.cpp.

See also

system geometry, system control port, system socket

system geometry

Name

system geometry - set the size of the (system) video mixer output frame

Synopsis

system geometry <width> <height> <fourcc>

Description

The command system geometry sets the system video base frame size width and height in pixels used for video mixing. The size of the base frame is also the size of the finished video frames that will be the video output of Snowmix. The command also defines the internal video format used by Snowmix. Currently Snowmix only supports ARGB as the format. The ARGB format is equivalent to the GStreamer format specified as:

GStreamer 0.10
'video/x-raw-rgb, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)65280, green_mask=(int)16711680, blue_mask=(int)-16777216, width=(int)WWWW, height=(int)HHHH, framerate=(fraction)RRRR, pixel-aspect-ratio=(fraction)1/1, interlaced=(boolean)false'

GStreamer 1.0
'video/x-raw, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)65280, green_mask=(int)16711680, blue_mask=(int)-16777216, width=(int)WWWW, height=(int)HHHH, framerate=(fraction)RRRR, pixel-aspect-ratio=(fraction)1/1, interlaced=(boolean)false'

In the given GStreamer format WWWW is the width in pixels, HHHH is the height in pixels and RRRR is the frame rate given as a ratio. A frame rate of 24 is given as 24/1 and 23.97 is given as 2397/100.

Example

    system geometry 1280 720 ARGB

See also

system frame rate, system control port, system socket

system host allow

Name

system host allow - control which hosts can establish a control connection.

Synopsis

system host allow [(<network> | <host>)[(&l;tnetwork> |<<host>)[ ...]]]

Description

The command system hosts allow can be used to control which hosts or network are allowed to establish a control connection to Snowmix. By default Snowmix only allows control connections from localhost 127.0.0.1. When used without argument, Snowmix will list the current settings for allowed hosts. The argument <network> must be specified as x.y.z.w/n where x.y.z.w is the network address and n is the number bits in the network mask equal to 1. The argument <network> must be specified as x.y.z.w. Hosts and networks are separated by spaces. If the command is used to extend the list of hosts and networks allowed t oconnect to Snowmix, the host localhost 127.0.0.1 should be included in the list. If not, connections from 127.0.0.1 will be dropped.

Example

    system host allow
    system host allow 127.0.0.1 192.168.0.3 10.10.1.0/10

See also

system info, system control port

system info

Name

system info - list system information

Synopsis

system info

Description

The command system info lists basic system information of Snowmix.

Examples

    system host allow

produces for a given setup the following output for Snowmix version 0.4.0

    STAT:  System info
    STAT:  System geometry     : 1024x576 pixels
    STAT:  Pixel format        : 
    STAT:  Bytes per pixel     : 4
    STAT:  Frame rate          : 24.000
    STAT:  Block size mmap     : 2359296
    STAT:  Frame sequence no.  : 12354
    STAT:  Ctr verbose         : no
    STAT:  Ctr broadcast       : no
    STAT:  Output ctr socket   : /tmp/mixer1
    STAT:  Output ctr fd       : 6
    STAT:  Video feeds         : loaded
    STAT:  Virtual video feeds : loaded
    STAT:  Video text          : loaded
    STAT:  Video image         : loaded
    STAT:  Command interface   : loaded
    STAT:  Audio feeds         : loaded
    STAT:  Audio mixers        : loaded
    STAT:  Audio sinks         : loaded
    STAT:  TCL interpreter     : loaded
    STAT:  Stack               : 0
    STAT:

See also

stat

system output buffers

Name

system output buffers - sets the number of frames allocated for output.

Synopsis

system output buffers <buffer count>

Description

The command system output buffers can be used to set the number of frames allocated for outputting mixed video. The frames are allocated as shared memory and will be shared with a GStreamer pipeline using plugin shmsrc. Default value is 20. Minimum value is 10 and maximum value is 1000, but the maximum value will also be limited by host ressources. The command must be executed before the system socket command.

Example

    system output buffers 50

See also

system info, system output delay, system output freeze, system output info, system output mode, system output reset, system output status

system output delay

Name

system output delay - delay the output stream a specified number of frames.

Synopsis

system output delay <frames>

Description

The command system output delay can be used to delay the output stream a number of frames specified by the argument frames. Mixed video frames are delayed for output until mixed frames ready for output is at least the specified number of delay frames. Minimum delay is 1 frame. Setting it higher than output buffers available will block video output. It is recommended that the delay is at least a couple of frames lower than output buffers specified. Default value is 1. The command has no effect for system output mode 0. The command is recommended to be set before the command system socket. The command is useful if audio output is late compared to video output.

Example

    system output delay 25

This example will keep a constant delay of 25 frames for its video output.

See also

system info, system output buffers, system output freeze, system output info, system output mode, system output reset, system output status

system output freeze

Name

system output freeze - freeze video output by outputting the same static frame.

Synopsis

system output freeze <number frames to freeze>

Description

The command system output freeze can be used to "freeze" the video output stream by repeating the same frame a number of times specified by the argument <number frames to freeze>. While the same frame is being repeated, new frames are being dropped. When the same frame has been repeated the specified number of times, the video output will flow normally again. This command has no effect in output mode 0 and 1.

Example

    system output freeze 300

This example will freeze the video output for 10 seconds assuming the framerate is 30 Hz.

See also

system info, system output buffers, system output delay, system output info, system output mode, system output reset, system output status

system output info

Name

system output info - List configured settings for output.

Synopsis

system output info

Description

The command system output info can be used to list information about the output configuration.

Example

    system output info
    STAT: system output info
    STAT:   Verbose           = 1
    STAT:   Socket name       = /tmp/mixer1
    STAT:   Socket master     = 6
    STAT:   Socket client     = -1
    STAT:   Memory handle     = /shmpipe.21228.    0
    STAT:   Memory size       = 47185920 (20 blocks, block size 2359296)
    STAT:   Output mode       = 0 (standard, no thread)
    STAT:   Freeze            = no (0 frames, 0.00 secs)
    STAT:   Delay             = 1 frames (41.7 ms)
    STAT:

This example will freeze the video output for 10 seconds assuming the framerate is 30 Hz.

See also

system info, system output buffers, system output delay, system output freeze, system output mode, system output reset, system output status

system output mode

Name

system output mode - sets the video output mode.

Synopsis

system output mode <mode>

Description

The command system output mode sets the way video output is handled. Currently 3 modes are available. The modes are:

• Mode 0 : Simple direct output handled in mixer main thread. Default.
• Mode 1 : Simple threaded. Buffers are placed in a queue and a second thread handles communicating for video out. Buffer are send as soon they are mixed and timing depends on the mixer loop timing.
• Mode 2 : As Mode 1, but communication out has an extra layer of timing. This mode is experimental and not fully tested.

The command must be set before the command system socket and can not be changed after the command system socket.

When using snowmix in loop mode 2 and output mode 2 and when Snowmix runs out of available shm buffers for video output, perhaps because the gstreamer shmsrc somehow runs slow, shm buffers will stay unavailable to the main video loop until at least half of the allocated shm buffers are available again. To use this feature, use the following cli option

    ./snowmix -l2 ../ini/.....

Example

    system output mode 2

See also

system info, system output buffers, system output delay, system output info, system output freeze, system output reset, system output status

system output reset

Name

system output reset - reset (close) the output connection.

Synopsis

system output reset

Description

The command system output reset will reset the control connection for the shmsrc connected to Snowmix by closing it. It is the responsibility of the shmsrc to detect this and reconnect if you want to.

Example

    system output reset

See also

system info, system output buffers, system output delay, system output info, system output freeze, system output mode, system output status

system output status

Name

system output status - list the status of the output connection.

Synopsis

system output status

Description

The command system output status will list the status for outputting video frames. The command list the following values:

• Connection Seq. no. : Number of times a connection was made.
• Frame number : Current frame number being outputtet.
• Timed frame loops : - (see code).
• Copied frames : - (see code).
• Frames dif/sent/ack : No frames dif for output/ack.
• Ready for output : No. of frames ready for output.
• Inuse : No. of frames currently in use.
• Repeated status : No. of frames repeated
• Timed loop frame p. : - (see code).
• Got no free buffers : Is output currently out of free buffers
• Last 3 frame periods : Frame period of last 3 frames.
• Frame p. min/ave/max : Min, average and max frame period of the last 50 frames.
• Frame info : Number of inuse for each allocated frames.

Example

    system output status
    STAT: system output status
    STAT: Connection Seq. no.  = 0
    STAT: Frame number         = 0
    STAT: Timed frame loops    = 0 frames
    STAT: Copied frames        = 0 frames
    STAT: Frames dif/sent/ack  = 0 (0/0)
    STAT: Ready for output     = 0 frames
    STAT: Inuse                = 0 of 20 frame buffers
    STAT: Repeated status      = 0 frames
    STAT: Timed loop frame p.  = 0.0 ms
    STAT: Got no free buffers  = no
    STAT: Last 3 frame periods = 0.0 0.0 0.0 ms
    STAT: Frame p. min/ave/max = 0.0 0.0 0.0 ms
    STAT: Frame info           = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    STAT:

See also

system info, system output buffers, system output delay, system output info, system output freeze, system output mode, system output reset

system socket

Name

system socket - set the mixer's control socket for output to GStreamer shmsrc

Synopsis

system socket <system socket name>

Description

The system socket command will set the system control socket to use for signalling to a GStreamer's module shmsrc the availability of a new frame for the module. The mixer currently only support one video output. From Snowmix version 0.5.0 it will be mandatory for the command system socket to use absolute path/file name starting with a leading '/'.

Example

    system socket /tmp/mixer-control-socket

The example sets the control socket for the mixers output to /tmp/mixer-control-socket. The GStreamer pipeline must then have a pipeline possibly beginning as shown below

    gst-launch shmsink shmsrc socket-path=/tmp/mixer-control-socket do-timestamp=true is-live=true ! $MIXERCAPS ! ......

The variable MIXERCAPS must include the following to match the Snowmix video format:

For GStreamer 0.10
'video/x-raw-rgb, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)65280, green_mask=(int)16711680, blue_mask=(int)-16777216,.........'

For GStreamer 1.0
'video/x-raw, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)65280, green_mask=(int)16711680, blue_mask=(int)-16777216,.........'

A full example can be seen in scripts/input2feed.

See also

system frame rate, system control port, system geometry

verbose

Name

verbose - be verbose to print more information

Synopsis

verbose

Description

The command verbose toggles the verbose flag for the module CController. This can lead to extra verbosity in the following modules: controller, video feed and video text. Future versions may increase verbose information for the controller module while the affinity with the modules video feed and text will be removed. The system command system info list the verbose state. From Snowmix version 0.4.1 when toggling verbose on will be reported. Toggling verbose in version 0.4.0 and earlier was silent.

Example

    verbose

See also

system info