The command 'audio feed close' can be used to force closing a control connection
connected to the audio feed, if any. It is an error to close an audio feed
that has no control connection connected to it. Closing an audio feed
will flush its buffers and change the state of the audio feed to disconnected
if it was in a state of pending, running or stalled. An external process
connected to the audio feed, may choose to connect again asap. The command
offers a way from Snowmix to tell an external connecting process to possibly
restart and reconnect. The syntax is:
audio feed close <audio feed id>
WARNING: This command may terminate Snowmix with a core dump. There
may be an resolved race condition, so do not use this command in a production
setup.
audio sink fadefactor
The command "audio sink fadefactor" can be used to control how much the RMS
value for a sink is reduced by at frame rate. The default value is 0.95 which will
provide the illusion of the RMS for falls towards zero slowly. The syntax is:
audio sink fadefactor [<audio sink id> <factor>]
Until this version, the RMS value(s) for an audio sink would be updated
with the RMS value for an audio buffer it received, if the RMS value of
the buffer was greater than the RMS value for the audio sink, otherwise
it would not. Then at framerate, the RMS value for the audio sink would be
reduced with 5% (multiplied with with 0.95). This created a form for slow
fading down for the RMS value shown graphically in snowaudio.tcl. From version
0.5.2, the same applies, but the RMS value(s) of the sink is at frame rate
only reduced if the last buffer buffer had an RMS value less than the current.
The comparison of this is done on a per channel basis, so if say left channel
last buffer had and RMS value that was greater, than the sinks RMS for that
channel, it will not reduce the RMS value at next frame. At the same time
the right channel may have had and RMS value for the buffer less than the sinks
RMS value for the right channel annd as such not the buffer value was not used
for updating the sinks right channel RMS value, but the right channels RMS
value will then be reduced.
audio sink tcp
The command "audio sink tcp" can be used to connect an audio sink to either
a remote or local Snowmix audio feed or a TCP listener. The syntax for the command
is:
Used without arguments, the command lists the tcp settings for all audio sinks.
Used with the argument sink id the command lists the tcp settings for the
specified audio sink, if it exists. Using the command with the additional argument
ip address and port, the specified audio sink is configured to connect
to the specified IP address and port number, when the audio sink is started. The
audio sink can be started using the command audio sink start <sink id>.
If the sink is to be connected to another possibly remote Snowmix audio feed,
the additional argument prepend string must be specified. The argument
prepend string must be the command that initializes the remote control
connection as an audio feed. Below is shown an example.
In the example above, the audio sink 7 will wen started connect to
IP address 10.0.0.2 port 9999 and send the string audio feed ctr isaudio 3
before sending audio data. A newline character is appended the prepend string
when sending. Note that the sending audio sink and receiving audio feed
must agree on sample rate, cannels and format for the setup to work normally.
A new framework named bgworker for threaded background jobs is now available.
It allows for some tasks to be executed in the background while Snowmix mixes
frames. This framework can be used to write images and the main mixer frame
to files asynchronously. It can also be used for filling new frames ready to
be used for mixing the main mixing frame. Additional functionality will
be added later. All bgworker commands can be shortened to bg.
The list of commands and syntaxes for the bgworker are:
bg add
bg del
bg fill [ (<mode> | value [ <fill value in hexadecimal> ]) ]
bg help [fill]
bg info
bg verbose [<level>]
Commands such as asynchronously reading and writing images/farmes to disk are
covered in sections for feeds, images and more.
bg add
The new command bg add will create a bgworker thread waiting for tasks to
execute. The syntax is:
bg add
bg delete
The new command bg delete will delete a bgworker thread waiting for tasks to
execute. The syntax is:
bg delete
bg fill
The command bg fill can be used to select the method for filling
every new frame to be used for mixing the main frame. The fill is so to speak
the background for mixed frames. The syntax for the command is:
bg fill [ (<mode> | value [ <fill value in hexadecimal> ]) ]
Used without argument, the command list the fill mode:
bg fill
MSG: bg fill 2 (Orc memset - from fill value )
Using the argument value, the command list the fill value:
bg fill value
MSG: bg fill value 0xff000000 mode 2 (Orc memset - from fill value )
To change the fill value, a fill value must be specified. The example below
illustrates this setting the background to solid white:
bg fill value 0xffffffff
The various fill modes available can be listed using the command
bg help fill:
bg help fill
STAT: bg fill mode for new output frames:
STAT: 0 : no fill
STAT: 1 : using memcpy of feed 0
STAT: 2 : using Orc accelerated memset and fill value
STAT: 3 : using Orc accelerated memcpy of feed 0
STAT:
bg help
The command bg help can be used to list the bgworker commands
available and their syntaxes:
bg help
STAT: Commands:
STAT: bg add
STAT: bg delete
STAT: bg fill [ (<mode> | value [ <fill value in hexadecimal> ]) ]
STAT: bg help [fill]
STAT: bg info
STAT: bg verbose [<level>]
STAT:
bg info
The command bg info can be used to list information about the
bgworker framework. The amount of information available may expand as new
tasks later becomes available as bgworker tasks. The bg info is shown
below:
bg info
STAT: bg workers info
STAT: verbose level : 0
STAT: workers : 4
STAT: worker seqno : 4
STAT: message count : 0
STAT: fill outframe : 2 (Orc memset - from fill value )
STAT: fill value : 0xffffffff
STAT:
bg verbose
The command bg verbose can be used to toggle or set the verbose
level for the bgworker framework. The syntax is:
bg verbose [<level>]
Used without argument, the verbose level
is toggled from a level larger than 0 to 0 or from 0 to 1. Used with
<level> argument, the command set the verbose level to the value of
<level>.
The command 'command addatline' for adding lines to an existing command
macro can now take negative number counting from the last line. So a line
number of -1 means the second last line, -2 means the third last line etc.
The syntax is now:
Snowmix 0.5.2 adds 9 new commands supporting "green screening" or "chroma keying" if you
like. The 9 new commands all start with feed chroma. Doing "green screening" on
Snowmix is a little CPU intensive, so multiple cores is an advantage. The format of the
feed selected for "green screening" has to be YUV. The formats availble are I420, Y42B
and Y444. The latter is the preferred format for best result. The format of a feed can
be set using the command feed format.
feed chroma angle
The new command feed chroma angle can be used to set the size of the color cube
setting the alpha value for pixels in an YUV frame selected for "green screening". The
syntax is:
feed chroma angle [<feed no> [<angle>]]
The optional paramter is a real (decimal) number between 0 and 89. Used without any
arguments, it will list the angle setting for all feeds. Used with a feed no as
argument, it will list angle setting for the specified feed if the feed exist.
feed chroma color
The new command feed chroma color can be used to set the color key used for
"green screening". When the key for doing "green screening" is set to color, the
values setable with this command is used for calculating the alpha value of each pixel
individual. Pixels with a color "close" to the value set, will have an alpha value set
close to 0 depending on the distance between the pixel's color and the color value
set with the command. Pixels with a color value with a distance far from the set
color value will have the alpha value of the pixel set to a higher setable value. This
value is normally 255, but can also be set with this command. The syntax of the command is:
feed chroma color [<feed no> [[<red> <green> <blue>] [<alpha>]]]
The command used without arguments, will list the chroma colour and alpha value settings
for all feeds. With a feed no argument as only parameter, it will list the same
but only for the feed indicated. If the arguments include values for red, green
and blue, these value will be set for the feed indicated by the feed no argument.
If the arguments in addition to the feed no and the red, green
and blue argument also includes the alpha argument, the max alpha for
the "green screen" calculations can be set. The alpha value can also be
set without the red, green and blue argument. The valid values
for the red, green, blue and alpha arguments are integers
between 0 and 255 both included.
feed chroma info
The new command feed chroma info can be used to list chroma setting for one or
all feeds. The syntax of the command is:
feed chroma info [<feed no>]
Depending on the configuration, an output may look like this:
feed chroma info
STAT: feed 0 off angle 00.0 black 000 white 000 noise 00.0 low 0 high 0 snapshot no color 000 000 000 alpha 0 key color table BT.709
STAT: feed 1 off angle 00.0 black 128 white 127 noise 02.0 low 0 high 255 snapshot no color 000 000 000 alpha 255 key color table BT.709
STAT:
feed chroma key
The new command feed chroma key can be used to set key type used for doing
"green screening". Snowmix supports two kind of keys. Either a single key or color can
be used or a snapshot with potential millions of individual colors can be used as a key.
The syntax of the command is:
feed chroma key [<feed no> [(color | snapshot)]]
Used without arguments, the command will list the key setting for all feeds. If
the feed no is specified only, the command list the key setting for the indicated
feed, if it exists. If the key argument is also included and the argument is set to either
color or snapshot, the key will be set to that for the feed indicated, if it exists. Using
snapshot as a key, require a snapshot to be taken using the command feed chroma snapshot.
feed chroma level
The new command feed chroma level can be used to set level of the parameters black,
white, noise, low and high. The syntax of the command is:
Used without arguments, the command will lists the level of the 5 parameters for all feeds.
With the feed no argument only, it will lists the 5 parameter values for the specific feed, if the
feed exists. Using the command with the feed no and one of the 5 parameter names, the command
lists the current setting for that feed for that parameter. Adding also a value, the value is
set for the specified parameter for the specified feed.
The noise level specify how much "noise" is tolerated while still lowering the alpha value
thus allow for transparency for each pixel. Low noise values are equal to sharp edges. Default value is 2
and allowed values are real numbers between 0 and 64 both included.
The black and white levels set the sensitivity to the black and white level of
luminosity. The default level is 128 for black and 127 for white. Allowed value
is an integer between 0 and 128 for black and an integer between 0 and 127 for
white.
The high and low level sets a level for additional modifying the alpha level
calculated by the chroma keying algorithm. Default level for high is 255 and 0 for
low. If the calculated alpha level is above the high value, the alpha level
is set to the specified alpha value set with the command feed chroma color. This
value is typical 255. If the calculated alpha level is below the low level, the
alpha value is modfied to A = (A*A / low) thus lowering the value.
feed chroma snapshot
The new command feed chroma snapshot can be used to take a snapshot for the specified feed.
The snapshot taken, can be used for chroma keying enabling individual chroma keys for each
pixel of the entire frame. If a feed is not in state RUNNING, the snapshot taking is delayed
until the feed enters the state RUNNING where the first frame available and snapshot is taken.
The syntax of the command is:
feed chroma snapshot [<feed no> [take]]
Used without arguments, the command will list the snapshot state for each feed. The state can be one
of 3 being "no", "taking" and "taken". If the command is issued with just the feed no argument,
the snapshot state for the specified feed is listed, if it exists. If the additional argument "take"
is also present, a snapshot will be taken of the first available frame available for the feed.
feed chroma state
The new command feed chroma state can be used to enable or disable chroma keying for a
specific feed. The syntax of the command is:
feed chroma state [ [(enable|true|on|1) | (disable|false|off|0)]
Used without arguments, the command will list the current the chroma keying state for all
feeds. Adding the argument feed no, the command will list the chroma keying state for
just the specified feed, if it exists. Adding a second argument being one of the listed
values, will either enable or dsiable chroma keying for the specified feed if it exists.
Note that to be able to do chroma keying, the format of the feed has to be I420, Y42B
or Y444.
feed chroma table
The new command feed chroma table can be used to select the conversion table used
for converting YUV to RGB for chroma keying. The syntax of the command is:
Used without arguments, the command will list the type of the current conversion
table for all feeds although if the feed format is not of the type YUV, this is not really
the case. Using the command with the argument feed no, the command will list
the name of the conversion table for the specified feed if it exists. Currently two
standard conversion tables are available being BT.601 and BT.709. A custom option
exists, but is has not been tested and may likely not work reliably. The command
can also be used to list the values for the selected table using the keyword 'list'.
feed chroma threads
The new command feed chroma threads can be used to set the number of threads used
for a specific feed to do chroma keying and YUV to RGB conversion. The default number of threads
is 1. Using more than one thread, only helps if the hardware offers more than one CPU
or core. Typical 4 or more cores will be needed before this command will make sense to use.
The syntax of the command is:
feed chroma threads [ [<no threads>]]
Used without arguments, the command will list the setting for all feeds. Specifying
the feed no as argument, will list the setting for just the specified feed,
if it exists. Adding a positive integer value being 1 or an equal integer, will set
the number of threads used for chroma keying for the feed indicated, if it exists.
The number of threads must be a positive integer that can divide the height of
a feed in pixels without remainder.
feed clip
The command feed cutout has been replaced by the command feed clip. The
command feed cutout will eventually dissapear with the next major update for
Snowmix and is marked in EndOfLifeAnnouncements.
The syntax is:
feed clip <feed no> <x> <y> <width> <height>
feed coor
The command feed shift has been replaced by the command feed coor. The
command feed shift will eventually dissapear with the next major update for
Snowmix and is marked in EndOfLifeAnnouncements.
The syntax is:
feed coor <feed no> <x> <y>
feed flip
The command feed flip can be used to flip a feed vertically and/or
horizontally. The syntax is:
The abbreviation "ver" and "hor" can be used for vertically respectively
horizontally. If a feed is flipped vertically and a shape macro using the
feed is placed, the feed is flipped vertically. If vertical flipping
is also specified for the feed in the shape macro, the result is no
flipping as 2 times vertical flipping cancels out flipping vertically. The same
applies for horizontal flipping.
Note: Flipping feed is alpha code. It does work for full screen feeds,
or feeds used in shapes, but is does not always work for scaled or offset or clipped feed used
directly using stack or feed overlay or possibly virtual feed overlay/vfeed overlay.
This will later be corrected.
feed format
The command feed format can be used to change the default feed
pixel format BGRA or RGBA depending on compile settings to another format.
A feed format can be one of either I420, Y42B, Y444, RGBA or BGRA. I420 is YUV planar
4:2:0. Y42B is YUV planar 4:2:2. Y444 is YUV planar 4:4:4. RGBA and BGRA are 32 bit with
the 8 bits value in the byte order R,G,B,A and B,G,R,A respectively independently of "Little Endian"
and "Big Endian". Note that Snowmix defines RGBA as stream order as one byte of red,
followed by one byte of green followed by one byte of blue followed by one byte of
alpha. Note that some systems and software defines RGBA as a 32 bit integer. On such
systems, if the hardware is little endian, what they define as RGBA, is stored in
memory in the order A,B,G,R, which is what Snowmix defines as ABGR.
The syntax for the command is:
Conversion from YUV to RGBA/BGRA will happen in an indepedent thread. As a side
effect, the converted frame may in some cases be one frame period delayed. However
frame conversion is done asynchronously indepedently from the steady frame period
of the mixer frame, so in the most cases, the delay may not be relevant.
The script input2feed will now query Snowmix for the format of a feed and set
its parameters accordingly converting the stream to the appropriate format.
feed idle
From version 0.5.2, Snowmix will cache loaded idle images and use these when
loading idle images into Snowmix. This prevents unnecessary duplication and
it speeds up the startup time in case of identical idle images.
The idle command can now also take images loaded with the image load
command as argument. The new syntax for the feed idle command is now:
If the loaded image does not exist, or the loaded image geometry does not
match the geometry of the feed, Snowmix will fallback to try loading a raw
image from a file named <loaded image id> using search path.
feed info
The command "feed info" will now print the format for the feed. Before version
0.5.2, the command could print something similar to this:
STAT: feed id : state islive oneshot geometry cutstart cutsize offset fifo good missed dropped <name>
STAT: feed 0 : STALLED recorded continuously 1280x720 0,0 1280x720 0,0 0:0 0 0 0 <Internal>
STAT: feed 1 : PENDING live continuously 1280x720 0,0 1280x720 0,0 0:10 0 85 0 <Feed #1>
It will now print something similar to this:
STAT: feed id : state islive oneshot format geometry cutstart cutsize offset fifo good missed dropped <name>
STAT: feed 0 : STALLED recorded continuously RGBA 1280x720 0,0 1280x720 0,0 0:0 0 0 0 <Internal>
STAT: feed 1 : PENDING live continuously RGBA 1280x720 0,0 1280x720 0,0 0:10 0 85 0 <Feed #1>
The tcl command "snowmix feed info geometry ..." will also print the format
name for the feed. The default format is either RGBA or BGRA depending on compiler
options set at compile time.
feed keeplast
When a feed is still connected (ie. the external shmsink is still connected) but
no longer receives any new frames and it has consumed frames in its queue, it will
return the last received good frame as long as its state is RUNNING rather than STALLED
or DISCONNECTED. A feed will when not receiving new frames, but it is still connected,
eventually enter the state STALLED. The time to enter the state STALLED is set with the
command feed idle where you set the time to enter STALLED in frame periods. By
default idle time is 0.
When a feed enters the state STALLED, it will no longer return the last received
good frame, but rather return the feed's idle frame if any, or a black frame.
When a feed enters the state DISCONNECTED, it will no longer return the last received
good frame, but rather return the feed's idle frame if any, or a black frame.
The new command feed keeplast can add frame periods keeping the last received
good frame. If set to 200 and idle set to 100, then the feed feed will return the last
received good frame for 300 frame periods before returning the idle frame. Again if
set to 200, the feed will return the last received frame for 200 periods after
disconnect. The syntax of the command feed keeplast is:
feed keeplast [<feed id> [<timeout in frames>]]
feed list
The command "feed list verbose" will now also print a line with the format of the feed.
Possible formats are RGBA, BGRA, I420, Y42B and Y444. The command will now also
will now also print the control socket fd for the feed, the shm name and the shm fd.
feed status
The new command "feed status" can be used to list the status for all feeds. The syntax is:
feed status
The command can be be abbreviated to feed sta.
feed onchange state
The command feed onchange state can be used to set a Snowmix command to
automatically being executed upon state change for video feeds. The syntax is:
feed onchange state [-1 | (<feed no> [<snowmix command>])]
When used without arguments, the command will list the general Snowmix command
to be executed upon state change for a feed. If none has been set, the command
will list an empty command.
When used with argument '-1', the command will list the specific Snowmix commands
for all feeds to be executed upon state change for a feed. If none has been set,
the command will list an empty command.
When used with argument being an existing feed number, the command will list the
specific Snowmix commands for the specific feed to be executed upon state change for
the feed. If none has been set, the command will list an empty command.
Adding the Snowmix command argument without feed number, sets the general command
to be executed upon feed change. If a feed number is included, the command is
set for the specific feed.
Executing of a command upon feed state change will prioritize command set
for a specific feed over the command set for general.
The command set to be executed will add feed id and state as argument. The example
below shows how this can be used.
feed onchange state tcl eval FeedStateChange
command create SomeProgram.tcl
proc FeedStateChange { args } {
set feed_id [lindex $args 0]
set feed_state [lindex $args 1]
puts stderr "Feed $feed_id changed state to $feed_state"
}
command end
tcl exec SomeProgram.tcl
command delete SomeProgram.tcl
The above example can produce this text entry on the Snowmix console:
Feed 4 changed state to RUNNING
The command can be abbreviated to "feed onch stat".
syntaxes for glshape modify, glshape vbo config, glshape vbo data, glshape vbo indices
glshape array modify
The new command glshape array modify to modify one or more entry values in a
created array. This is significantly faster than deleting the array and creating it again
with changed values. The syntax is somewhat similar to the glshape modify command.
The syntax is:
The new command "glshape help client_state" will list available
arguments for the in the "glshape client" command.
The equivalent OpenGL function is glEnableClientState(). Se more
on glEnableClientState() here
glEnableClientState.
glshape cullface
The new command glshape cullface can be used to control how OpenGL does culling.
is equivalent to OpenGL glCullface(). The syntax is:
glshape cullface <glshape id> <cullmode>
The command glshape help cullmode can be used to list valid arguments for cullmode.
glshape drawarray
With the command glshape drawarray is it possible from within
a shape macro to order drawing/rendering of primitives from a defined
array. The syntax is:
The new command "glshape help array_mode" will list available
options for the argument. The equivalent OpenGL
function is glDrawArrays(). Se more on glDrawArrays() here
glDrawArrays.
glshape list (comments)
The command glshape list can now with the optional parameter
list the comments for a shape command in a shape macro if present. The
syntax is now:
glshape list [<glshape id> [comments]]
If the the option "comments" is present, the listing will include
comments for individual shape entries if such a comments where
added while created. And example of this could be:
gl add 1 my shape
gl noop 1 # This is my comment to the command noop
gl list 1
STAT: shape 1 ops 1 name my shape
STAT: - 1 noop
STAT:
gl list 1 comm
STAT: shape 1 ops 1 name my shape
STAT: - 1 noop # This is my comment to the command noop
STAT:
Here the part "# This is my comment to the command noop" is
the comment. Comment part is recognized as the text following '#'
in a glshape command. A few glshape commands may not accept comments.
Please report when found. Commands including defining a name does
not recognize the '#' as a mark of a comment but rather sees it
as part of the name. And example would be:
glshape add 1 This is my name # yes it is
Here the name will be "This is my name # yes it is"
The syntaxes for the commands glshape modify, glshape vbo config,
glshape vbo data and glshape vbo indices was listed wrong in the
help section. The correct syntaxes are:
The parameter is the entry line number in the glshape
macro that is to have one or more of its values changed. You do not
change the entry type with this command, but rather the values of
the entry. If glshape macro 15 has an entry with four values a, b,
c and d in line 7 and you wish to change b and d, the command would
be:
glshape modify 15 7 2,4 9.001 11.05
The command glshape help modify will list the glshape macro entries that can
be changed using glshape modify. The list will depend on the hardware and
version of OpenGL library linked with Snowmix at compile time.
glshape help modify
The new command 'glshape help modify' will list the glshape macro
entries that can be changed using 'glshape modify'. The list will
depend on the hardware and version of OpenGL library linked with
Snowmix at compile time. Below is an example of how it can look:
glshape help modify
MSG: List of glshape elements where its parameters can be changed with the modify command:
MSG: : arcxz , arcyz , arcxy , clearcolor , color3
MSG: : color4 , gluperspective , frustum , normal , ortho
MSG: : rotate , scale , scissor , texcoord2 , texcoord3
MSG: : texcoord4 , translate , viewport , vertex2 , vertex3
MSG: : vertex4
MSG:
The abbreviation "ver" and "hor" can be used for vertically respectively
horizontally. If an image is flipped vertically and a shape macro using the
image is placed, the image is flipped vertically. If vertical flipping
is also specified for the image in the shape macro, the result is no
flipping as 2 times vertical flipping cancels out flipping vertically. The same
applies for horizontal flipping.
Note: Flipping image is alpha code. It does work for full screen images,
or images used in shapes, but is does not always work for scaled or offset or clipped images used
directly using stack or image overlay or possibly virtual feed overlay/vfeed overlay
using a flipped image as its source. This will later be corrected.
image index
The new command image index can be used to split up a loaded
image into NxM smaller indexed images and stores them all under the image
being indexed. This is useful if the loaded image is stitched together of
smaller identical sized images.
Assume a loaded image with the geometry 800x300 is stiched together by 24
images in 3 rows each with the geometry 100x100 and arrange so the second smaller
image is right to the first smaller one and the 9th image is below the first
smaller image etc. in the following arrangement:
When the image is indexed with the command "image index 8 3"
the loaded image change geometry to new_width = width/cols and
new_height = height/row and have rows*cols smaller images indexed.
This is useful for image animation. The syntax is:
image index <image id> <cols> <rows>
The values of rows and cols must be selected in a ways so the division
of the loaded images width divided by cols has no remainder. The same applies
for height and rows. Note that the geometry of a loaded image will change
geometry to a smaller geometry when indexed by slitting it up.
When an image is indexed, the image returned when referenced can be
controlled by the new commands image index incr and image index set
The new command image index incr can be used to advance an indexed
image's index pointer. When an image is referenced, the image index pointer
dertermine which of the index image's su images that are returned. This command
is useful for image animation. The syntax is:
image index incr <image id> [<incr value>]
When the command is used with the argument <image id> but without the
argument <incr value>, the index pointer of the image will increment
by one meaning the index pointer will advance to the next index in the image.
If the index pointer already was pointing to the last image in the index
list, the pointer will now point to the first image in the list.
The new command image index set can be set to directly control the
index pointer of an indexed image. This is useful for image animation. Index
pointer position is counted from 0. The syntax is:
image index set [<image id> [<index>]]
If the command is used without any argument, the command will list the
current index of indexed images. This is shown below:
image index set
STAT: image 2 index 0 of 3
STAT: image 3 index 159 of 300
STAT:
If used with just the <image id> argument, the command will list
the index pointer setting for the image for just the indicated image. If used
with both the <image id> and the <index> argument, the
index pointer will be set to that value for the indicated image. However the
index value is set taking the modulus:
The new command image index load can be used to load images into
a single loaded indexed image. Normally when you load an image to an
image place holder that is already occupied, the already loaded image is
deleted. When loading additional images as indexed into an already loaded
image, the additional images are added as indexed to the original loaded
image and the loaded image place holder can be used as an indexed image
using the commands image index incr and image index set.
This is useful for image animation. The syntax is:
image index (load | loadasync) [<image id> [<file name>]]
The command support loading images both synchronously and asynchronously.
Loading an image synchronously means the command will not return before
the image is loaded and available. Loading an image asynchronously, means
the command will return as soon as possible while the image is loaded
in another thread in the background and the image may not be available
immediately. While loading images synchronously when Snowmix is starting
up may be the right choice, loading images asynchronously should be the
preferred method when Snowmix is mixing video to avoid possibly stalling
Snowmix if loading takes several ms or tens of ms. This is
important.
When an image is loaded, the image load command will read the image
from the harddisk, decode the image and write the raw image to memory before
returning. This is fine when images are loaded upon startup of Snowmix. This
may not be okay if a large image or many images are loaded when Snowmix is
running because reading from disk and decoding the image can take so long
time that it delays the mixing of video frames. The image load command
can now offer to load an image asynchronously using the new bgworker framework
loading the image in the background in another thread. Asynchronously loading
images will return immediately. If the chosen image id is valid for asynchronously
image loading, the command will return and report succes immediately. The loading
itself may fail when the bgworker tries to load the image and imformation
about it will be reported on stderr of Snowmix. The syntax is:
To see or detect when the image has been loaded, the image can be listed using
the command image load without arguments or similar method through the python
or tcl interpreter. This is shown below where image 10 is checked:
tcl eval set a [snowmix info image load 10]
Assuming image 10 did not exist before it was loaded asynchronously, the tcl variable
a will be empty if the image was not finished loading when the command was executed.
image pixel
The new command image pixel can be used to query or set a
pixel value for a loaded image. The syntax is:
The command is primarily for testing and debugging. It is not a very efficient
way for changing larger number of pixels in an image and it should not be used
for that after Snowmix is up and running.
If an image has transparency and if the alpha value for some pixels are
between little above 0 and little less than 255, the library of Cairo
Graphics Snowmix is using, would calculate saturated or clamped pixel values
that in some cases would be far from desired result. The new command
image premultiply fixes this. The syntax is:
image premultiply (on | off | <image id> [<alpha>]
If premultiply is turned on, an image RGB pixel values are premultiplied
with their alpha value upon loading.
Using the <image id> argument, an image RGB pixel values are
premultiplied with each pixel's alpha value upon executing the command.
Using both the <image id> and the <alpha> value argument, the
value is set as the image alpha value for each pixel. The <alpha>
value is given as a floating point value between 0 and 1. After that the command
can be executed again with only the <image id> to premultiply with
the set value.
The command image premultiply is important when using images with
transparency.
image write
The command image write has been changed in two ways. First, the command now
takes a copy of the image and ask a bgworker thread to write in the background to disk
thus not delaying the main mixer thread. Secondly, if the filename
is ending in .png, the image written will be written as a PNG file. Otherwise the
file written will be raw RGBA or BGRA bytewise depending on the internal colour format
set at compile time. Because it is a copy that is written, deleting the image immediately
after the image write command will not affect the writing. The syntax is:
The monitor system for Snowmix version 0.5.2 has been expanded a bit. A
monitor now have a monitor id and have to be created first. However by default
Snowmix itself creates a monitor with the id 0. A monitor also have to have
a source. By default monitor 0 has the main mixer frame as source.
A monitor can be displayed (requirering X-Windows running) using the
command monitor on, monitor fullscreen or monitor border.
A displayed monitor can be turned ofd using the command monitor off
or pressing the escape key on a keyboard that have focus in the monitor window.
The syntax of the commands are:
monitor (on | off | full | border) [<monitor id>]
Used without arguments, the command list information on all monitors shown
in the example below:
In the example above, two monitors are defined. Monitor 0 is sourced
by the main mixer frame and monitor 3 is sourced by feed 1. Both monitors
has the offset set to 0,0 and the geometry set to 0x0. The latter means the
monitor window will, when displayed, get the size of the source.
When a monitor is displayed using the argument on a window will
be created without borders depending on the window manager running. If the argument
is full the monitor is displayed with no borders and scaled to
fullscreen. If the argument borde is given, then a window with borders
is displayed. If the command is issued without the argument monitor id, the
monitor id is assumed to be monitor 0.
Monitor on Raspberry Pi works a
bit different as no X-windows is required. However all Raspberry Pi integration has
been postponed to version 0.6.0 due to change in Raspberry Pi firmware.
monitor add
If more than the default monitor is required, more monitors can be defined
using the new command monitor add. The syntax is:
monitor add [<monitor id> [<monitor name>]]
Used without arguments, the command will list defined monitors. Used with
the argument <monitor id>, the command will in line with other
Snowmix add commands delete the monitor with the id <monitor id>
if it exist. If the argument <monitor name> also is specified, a monitor
with the given <monitor id> and <monitor name> is created.
monitor aspect
The new command monitor aspect can be used to force keeping aspect ratio
for displayed content in a monitor window. The default value is on. If the aspect is
off, content may change aspect when displayed in a monitor window. The syntax for the
command is:
monitor aspect [<monitor id> (yes | on | true | 1 | no | off | false | 0)]
Used withouth arguments, the command will list the current aspect value for monitors
defined. Used with the monitor id argument, the command will list the state
for just the indicated monitor, if it exists. Adding the second argument being one
of the listed, will either set the aspect value to on or off depending on the argument
value.
monitor bgworker
The new command monitor bgworker can be used to enable displaying monitor
content in a second thread. For multi core systems, this allows more CPU being spent
for mixing video. The syntax of the command is:
monitor bgworker [(yes | on | true | 1 | no | off | false | 0)]
Used without, the command will list whether monitor content when displayed
will use a separate thread or not. Using one of the keywords shown, the
bgworker for monitor can either be turned on or off.
WARNING - WARNING
The bgworker for monitor should not be used. The current implementation is not
not thread safe and it will eventually crash Snowmix.
monitor center
The new command monitor center can be used to enable or disable centering
content in monitor window. The default value is on. The syntax of the command is:
monitor center [<monitor id> (yes | on | true | 1 | no | off | false | 0)]
Used without arguments, the command will list the center setting for all monitors defined.
Used with the monitor id argument, the command list the center setting for just the
indicated monitor if it exists. Adding the second argument being one
of the listed, will either enable or disable centering content for the specified monitor,
if it exists.
monitor coor
The new command monitor coor can be used to set the cooridnates on the screen
a monitor window will be displayed when displayed. The syntax of the command is:
monitor coor [<monitor id> <xoff> <yoff>]
Used without arguments, the command will list the coordinates for all defined monitors.
Used with the arguments monitor id, xoff and yoff, the command will
set the x and y offset coordinates for the monitor indicated if it exists.
monitor display
If the hardware Snowmix is running on, has multiple displays connected, setting the monitor
display number can be useful as it to some degree controls which display a monitor will appear
when enabled. The syntax for the command is:
monitor display [<monitor id> <display id>]
The default display id for all monitors created is 0. When the command is executed
without arguments, it will list the display id setting for all monitors.
monitor geometry
The command monitor geometry can be used to inspect or set the geometry
for a monitor. By default the monitor geometry is 0x0 meaning it will have the
geometry size of its source. The syntax of the command is:
monitor geometry [<monitor id> <width> <height>]
When the command is used without arguments, it will list the geometry for all
monitors. To change the geometry for a monitor, use the command with the monitor id
and the width and height argument. The geometry is given as positive integers.
monitor scale
The new command monitor scale can be used to enable or disable scaling
content in monitor window. The default value is off. The syntax of the command is:
monitor scale [<monitor id> (yes | on | true | 1 | no | off | false | 0)]
Used without arguments, the command will list the scale setting for all monitors defined.
Used with the monitor id argument, the command list the scale setting for just the
indicated monitor if it exists. Adding the second argument being one
of the listed, will either enable or disable scaling content for the specified monitor,
if it exists.
monitor source
The new command monitor scale can be used to set the source for a defined
monitor. By default the monitor 0 has set the source being frame 0. The source
of a monitor can be one of either frame, feed or image. The frame is the system mixer
frame and currently only frame 0 can be selected when selecting frame.
The syntax of the command is:
monitor source [ (frame | feed | image) ]
When used without argument, the command will list the source for all defined
monitors. Setting the source for a monitor require the 3 arguments being the
monitor id, the source type and the source id.
monitor help
The command monitor help list the syntax for the available
monitor commands. This is shown below:
monitor help
MSG: Commands:
MSG: monitor [info]
MSG: monitor (on | off | full | borderless) [<monitor id>]
MSG: monitor add [<monitor id> [<monitor name>]]
MSG: monitor aspect [<monitor id> (yes | on | true | 1 | no | off | false | 0)]
MSG: monitor bgworker [(yes | on | true | 1 | no | off | false | 0)]
MSG: monitor center [<monitor id> (yes | on | true | 1 | no | off | false | 0)]
MSG: monitor coor [<monitor id> <xoff> <yoff>]
MSG: monitor display [<monitor id> <display id>]
MSG: monitor geometry [<monitor id> <width> <height>]
MSG: monitor scale [<monitor id> (yes | on | true | 1 | no | off | false | 0)]
MSG: monitor source [<monitor id> (frame | feed | image) <source id>]
MSG: monitor verbose [<verbose level>]
MSG: monitor help
MSG:
monitor verbose
The new command monitor verbose can used to set the verbose level for
monitor. The syntax of the command is:
monitor verbose [<verbose level>]
Used without argument, the command toggles the monitor on and off like all other verbose
commands of Snowmix. To see the verbose level, use the command monitor info.
A verbose level of 0 turns of verbosity. A level of 1 or higher, turns on
verbosity. The higher the level is, the more info will be listed. Most extra verbose
information will only be listed on stderr (snowmix console).
If enabled at compile time, Snowmix supports an embedded Python interpreter
for Python scripting. When creating commands containing a Python script, the
names of a command macro with the Python script MUST be ending in '.py'. This
ensures that normal procedure for parsing input where multiple consequtive spaces
are replaced by a single space is suspended. Example:
command create MyPythonScript.py
a = 2
b = 2
c = a + b
print(c)
command end
python exec MyPythonScript.py
Using .py as ending for command name also suspend the normal Snowmix
setup parsing taking place whenever you create a new Snowmix macro (checking
for if-then-else, labels, goto etc). This is equivalent to what happens
for command macros containing tcl scripts identified by the .tcl ending.
All python commands python something can be shortened to pyt something.
Note the lack of indentation when creating MyPythonScript.py. You have to
follow the rules of indentation for Python. This can make it harder to
read Snowmix ini files with python scripts.
python exec
The command python exec can be used to execute a python script
previously saved in a command macro with the extension .py. The script
is executed in the embedded Python interpreter if it has been enabled at compile
time. The command is equivalent to the tcl exec command. The syntax is:
python exec <name of command macro containing python script>
python eval
The command python eval can be used to execute a python statement or
statements in the embedded Python interpreter if enabled at compile time. The
command is equivalent to the tcl eval command. It is legal to execute
mutiple python statements separated by semicolon. Example:
python eval a = 1 ; b = 2 ; c = a + b ; print(c)
The syntax is:
python eval <python statements or statements>
Python access to Snowmix internals
The embedded python interpreter can access Snowmix internals pretty much the
same way Snowmix internals are accessed in tcl. In Python the intenals are
accessed using the method snowmix.info. Results are returned as a Python
List. To get the geometry of all feeds, the following command can be executed:
python eval a = snowmix.info("feed geometry all") ; print(a)
The variable a would be printed to the Snowmix Console control connection because
stdout and stderr is directed to the Console. The output could look like this:
Obviously the string within the '"' has to be adjusted to express the information
you want. You don't litteraly write snowmix.info("audio (feed|sink) ...") but rather
write:
tcl eval a = snowmix.info("audio feed info all")
python reset
The command python reset which is similar to tcl reset command
except this command deletes the embedded python interpreter and initialize a new
one if the python interpreter has been enabled at compile time. The syntax is:
python reset
python help
The command python help which is similar to the tcl help
command listing the help info for the embedded Python interpreter. The syntax
is:
python help
Snowmix commands
Three new commands are added to the internal python interpreter. The first
two commands are commands enabling executing Snowmix commands from within
the interpreter. The syntaxes are:
The parses variant is identical to the parse variant with the
exception it will not write anything to the control connection it is being executed
through.
The third command enables writing messages back to the control connection the
command is executed through. This is shown below:
python eval snowmix.message("hello world")
This produce the same result as the Snowmix command message hello world, but
the execution takes place from within the embedded interpreter. This is equivalent
to the command tcl eval message hello world.
The shape help command did not list the commands shape alphaadd and
shape alphamul. The commands will either add a value to the current alpha level in
a shape or multiply the current alpha level in a shape with a value. The syntaxes are:
With the two new commands shape alphasave and shape alpharestore
it is now possible in a shape macro to save the current alpha level and to restore
a saved alpha level within the shape macro. Restoring alpha values beyond the list
of saved alpha values are ignored. The list of possibly saved alpha values are not
recursively available and any alpha value saved in a shape included in another shape
is not available for restoring. The syntaxes are:
The command shape help modify can be used to list the commands that can
be modified using the command shape modify The following shape entries
can currently (version 0.5.2) be changed using the shape modify command:
The scale_x and the parameters are now optional and default value is -1.
The optional parameters xx and yy that controls directions thus enable flipping are
by default when omitted set to 1. The sign of the optional xx and yy arguments controls flipping
the feed or image used in the macro. Setting xx to -1.0 flips the feed or image vertically. Setting
the yy to -1.0 flips the feed or image horizontally. Seeting the arguments to 1.0 and 1.0 disables
flipping. Using values other than -1.0 and 1.0 scales the feed. The xx> and the yy are
equivalent to the variables in the Cairo Matrix using the same names. See
Cairo Transformations
and cairo_get_matrix and cairo_set_matrix. See also
cairo-matrix-t.
For the scale argument for the command, this is left unchanged. The scaling is applied using the
following rules:
scale_x < 0.0
relative scale - scale positively from whatever shape is scaled to.
scale_x = 0.0
no scale - follow whatever the placed shape is scale to
scale_x > 0.0
absolute scale - scale absolute taking into account scale of shape
The command shape help was previously not listing the correct syntax for the command shape feed.
shape modify
The command shape modify can be used on the fly to change individual values
for a shape entry in a shape macro. The syntax is:
The parameter <entry id> is the entry line number in the shape macro that is
to have one or more of its values changed. The command does not change the entry type
with this command, but rather the values of the entry. If shape macro 15 has
an entry with four values a, b, c and d in line 7 and you wish to change b and
d (counting from 1 b=2 and d=4) to 9.001 and 11.05 respectively, the command would be:
shape modify 15 7 2,3 9.001 11.05
shape offset
The command "shape offset" can be used to add a given offset to absolute coordinates.
This affects shape macro command such as "moveto", "lineto", "arc_cw", "feed"
and "image". The offset is by default 0,0 and changing offset will be inherited
recursively down, but not up. If offset in shape N and the shape calls shape M
which sets offset to a non zero value, offset is still 0,0 in shape N when
execution of shape M ends and the macro execution of shape N continues. The
syntax is:
All system commands can now be shortened from "system something" to "sys something".
system ctr id
The command system ctr id will list the controller connection id which is a unique
sequence number for each control connection. It is 32 bit unsigned integer that will wrap to
zero at 2 to power of 32. It is useful for the commands messagec and
system ctr onclose. The syntax is:
system ctr id
system ctr onclose
The command system ctr onclose can be used to execute a Snowmix command when the
control connection the command is executed via closes. This is usefull if advanced scripting
is used to write perhaps frequent status updates to a control connection. To avoid inefficient
scripting, the command can be used to ensure cancellation of such writings upon closing the
control connection. But of course, this depends on the actual scripting.
system ctr onclose [<snowmix command>]
system control port
The syntax for the command "system control port" for setting the
TCP listener port, has been expanded to also be able to list the
current value. The syntax is now:
system control port [ <port number> ]
The keyword "system control" can be abbreviated to "sys ctr as
shown below:
sys ctr port [ <port number> ]
system frame write
The command system frame write can be used for writing the main mixer frame
to a file while Snowmix is running. The writing takes place in the background by
a bgWorker thread taking a copy of the mixer frame. The syntax is:
system frame write <mixer frame id> <filename>
Currently the 'mixer frame id' must be '0'. The written file will be a PNG file
using 32 bit RGBA. It is recommended that the filename uses the extension 'png', but
this is not enforced.
system keyhandler
The new command system keyhandler makes it possible to catch
keypress events and call a snowmix command with the event information.
It is only possible to catch keypress events if a monitor has been enabled.
In most cases it will only make sense to forward the event to a tcl or
python function. The syntax is:
system keyhandler [<snowmix command>]
Setup Example 1:
system keyhandler tcl eval MyKeyboardHandler
monitor on
Setup Example 2:
This example require the embedded Python interpreter to be included at compile time.
The default compile setting for Snowmix 0.5.2 is not to include Python.
system keyhandler python eval MyKeyboardHandler
monitor on
In the first example the following commands are executed in case of keyboard
press and keyboard release:
The first parameter in paranthesis is the monitor id receving the event.
In all cases, KEY_CODE is substituted by an integer value depending on key.
IMPORTANT: If the following configuration is done:
system keyhandler MyMacro
and MyMacro exist as a Snowmix command macro, then the following command
is executed, which has limited use because the KEY_CODE and UP/DOWN info is lost:
MyMacro
system mixer
If no external pipeline with a shmsrc is connected to Snowmix for getting
mixed frames, Snowmix by default skips mixing frames. This has some consequences.
If a monitor is enabled, the mixed frame does not get updated because no frame
is being mixed. Also the Snowmix command macro associated with the command overlay finish
does not get executed. This behaviour is defined as ondemand mixing.
If mixing should take place disregarding whether the mixed frames are being
consumed by an external pipeline, the system mixer must be changed from
ondemand to always. The command to do this is the system mixer
command. The syntax is:
system mixer [(always | ondemand)]
The default setting is ondemand. If the command is used without argument,
the command will list current setting. This is shown below:
system mixer
STAT: System mixer : ondemand (output not connected)
system mousehandler
The command system mousehandler can be used to forward mouse events to
to any Snowmix command. However for most cases it will only make sense to forward
the event to a tcl or python function. The syntax is:
system mousehandler [<snowmix command>]
Note that the mousehandler will only catch mouse events if the monitor function
is set to run and the window or fullscreen actually receives the event.
This functionality is similar to the command "system keyhandler" described above.
Please see there for details on what to set as a mouse handler function. If
the command for the mouse handler is "tcl eval MyHandler" (or "python eval Myhandler")
the Myhandler function will be when a mouse event occur called with the arguments:
The first argument is the id of the monitor receiving the event.
1The second argument "1" set it as a mouse button press or release event. For mouse motion
event the second argument is 2 and for a wheel event the second argument is 3.
The <which> parameter should identify the mouse although this seems to fail on some platforms.
The state argument depends on button states. Calling the embedded python interpreter requires
the inclusion of the interpreter at compile time, which is not the default compile setting
for Snowmix 0.5.2.
system mousemotion
The command system mousemotion can be used to enable forwarding mouse motion
and mouse wheel events to the mouse handler, also when no mouse button is pressed. By
default the mouse motion is set to 'auto'. When in auto mode, mouse motion and wheel events
are only forwarded when a mouse button is pressed. When mouse motion is set to off,
mouse motion and mouse wheel events are dropped. When motion mode is set to on, mouse
motion and wheel events are always forwarded to mousehandler. When the command is
used without arguments, the mousemotion mode is listed. The syntax is:
system mousemotion [(auto | on | off)]
system stacking
By default Snowmix will when starting mixing a new main frame copy feed frames
into and onto the current main mixer frame overwriting it. In effect the feeds are
stacked ontop of the current main mixer frame. The feeds that are stacked this way
are the feeds in the stack list. The stack list can be be set using the command
stack with the feed ids as argument and the argument order controls the order
of the list. The first feed in the stack list will always be a feed the same size
as the main mixer frame thus ensuring a new main mixer frame is always completely
overwritten. If no feeds was specified to be stacked, the stack list will have
the system feed 0 in the list. The system feed 0 will always have the same size
as the main mixer frame and the system feed 0 is by default black ensuring a
black background to mix or overlay upon. That said, the system feed 0 can be given
an idle image and that image may not necessarily be completely black. Because the
system feed 0 is always stalled, it will always return its idle image.
If another feed has the same geometry as the main mixer frame and if that feed
is to overlay and fill the main mixer frame completely, Snowmix can save a memory
copy setting the stack list to start with that feed and not the system feed 0.
Now if we know we are going to fill the main mixer frame completely perhaps
overlaying an image or multiple images or overlaying other objects such as shapes
or text with solid background enabled, stacking the system feed 0 or another feed
onto the main mixer frame is unnecessary. Normally stacking a single feed will only
use a small fraction of the CPU time available for mixing a frame, but if your
hardware is a small slow computer or you mix very large frames such as 4k or
8k, you don't want to do something that may be unnecessary. Also unecessary
stacking will invalidate part of your CPU's core cache, which can have a significant
impact on overall performance. For this reason, it can be advantegeous to be
able to prevent stacking from taking place. Because we can't empty the stacking list
a command to disable stacking is available. The syntax of the command to disable
stacking is:
system stacking [(0 | 1)]
Used without argument, the command list the current state. Using the argument
0 or 1 will respectively disable and enable stacking. The keywords off and on can
also be used.
snowmix info audio feed, snowmix info audio mixer, snowmix info audio sink
snowmix info glshape
The new embedded tcl command snowmix info glshape can now be used to query glshape
similar to the embedded tcl command for query shapes. The syntax is:
snowmix info glshape (info | list | place | move | alpha | texture | vector | array | vbo | vbodata) ( format | ids | maxid | nextavail | <id_list> )
Availability requires at least one of OsMesa, GlX or Egl being enabled when Snowmix was built.
If the embedded Python interpreter is enabled when built, the command is available as method as:
snowmix.info("glshape .....");
snowmix info shape
The existing embedded tcl command snowmix info shape can now be used to query patterns.
The new syntax is:
snowmix info shape (info | list | place | move | alpha | pattern | pdata) ( format | ids | maxid | nextavail | <id_list> )
As always examples of id_list are:
23
7 14 3
14..25 27..end
all
tcl help
The command tcl help was previously not listing the command that silently can execute a
snowmix command within the interpreter. The missing command to be listed was this:
tcl eval snowmix parses <snowmix command>
The command is similar to tcl eval snowmix parse without the 's' with the exception that execution is silent.
No output will be sent to the control connection on which the command was executed.
snowmix info adudio feed/mixer/sink
Adding listing name to the tcl command "snowmix info audio feed info",
"snowmix info audio mixer info" and "snowmix info audio sink info"
The changed format string can be queried as always using the tcl
command "snowmix info audio feed info format" now returning for feed,
mixer and sink respectively:
id rate channels signed bytespersample inidelay name
id rate channels signed bytespersample name
id rate channels signed bytespersample delay name
The embedded Python interpreter can do the same with the method
snowmix.info.
The command messagec can be used to write messages to another existing control connection.
The command require identifying the control connection by its unique id being a 32 unsigned
sequence number. The ctr id of a control connection can be listed using the command
system ctr id on the control connection. The syntax for the messagec command is:
messagec <ctr id> <message>
The command can together with system ctr id and system ctr onclose be used
for scripting to create more efficient ways for polling info on data thas has changed
among other things.
maxplaces
New commands to dynamically expand the place holders (maxplaces)
for text, image, vfeed, shape, glshape, audio feed, audio mixer and audio
sink. Currently, the number of place holders can only be expanded, not
shrinked. The syntaxes are:
These commands do not have the limitation the original command maxplaces
has. The original maxplaces command would need to be executed before the
involved module is loaded (is referenced). WARNING. Do not add more
place holders for each type than you need. Adding more than you need
may in some cases increase the time it takes to mix each frame. So be
conservative and keep the numbers low. The syntax had been added to
the help command for each sub module.
BGRA and RGBA
By default, Snowmix's internal colour format is bytewise BGRA. This can be changed at
compile time and set to RGBA. On some systems using RGBA can be faster for primarily
the glshapes copying images and frames from and to the GPU, on some
systems BGRA is faster. On many systems it makes no difference. For information
on how to change the default settings for internal colour format at compile time,
please refer to the compile, test and install page.
The command system info will now list the internal colour format. This information
is important to get for an external script that will connect to Snowmix to get the
output of the mixed frames.
