Reference Texts

Reference Manual - Texts

This reference manual is under development. More to come later.

Updated for Snowmix 0.4.5. Please note that many "text place ..." commands in version 0.4.4 changed syntax to "text ...".

This is the reference manual for Snowmix for the text commands. 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

• text align - Align place text or list alignment for placed text.
• text alpha - Set alpha for placed text or list alpha value for placed texts.
• text anchor - Anchor placed text or list anchoring for placed text.
• text backgr - Set/remove background for placed text or list values for background for placed texts.
• text backgr alpha - Set alpha for background for placed text or list alpha value for background for placed texts.
• text backgr clip - Set clip parameters for background for placed text or list clip parameters for background for placed texts.
• text backgr linpat - Define a linear pattern set for background for placed text or list values for linear pattern sets for background for placed texts.
• text backgr move alpha - Set animation value for alpha for background for placed text or list values for animation for alpha for background for placed texts.
• text backgr move clip - Set animation value for clip for background for placed text or list values for animation for clip for background for placed texts.
• text backgr round - Set round or rectangle corners for background for placed text or list values for corners of background for placed text.
• text backgr rgb - Set colour and optional alpha for background for placed text or list colour and alpha for background for placed texts.
• text clip - Set relative clip parameters for placed text or list relative clip parameters for placed texts.
• text clipabs - Set absolute clip parameters for placed text or list absolute clip parameters for placed texts.
• text coor - Change coordinates for placed text or list coordinates for placed texts.
• text font - Define a font set or list defined font sets.
• text font available - List available fonts on system.
• text grow - Let the number of characters shown for a placed text grow/increase or diminish/decrease.
• text help - List help for text commands.
• text move alpha - Set animation value for alpha for placed text or list values for animation for alpha for placed texts.
• text move clip - Set animation value for clip for placed text or list values for animation for clip for placed texts.
• text move coor - Set animation value for coordinates for placed text or list values for animation for coordinates for placed texts.
• text move rotation - Set animation value for rotation for placed text or list values for animation for rotation for placed texts.
• text move scale - Set animation value for scale for placed text or list values for animation for scale for placed texts.
• text overlay - Overlay placed text.
• text place - Place text or list placed texts.
• text place font - Change font set for placed text or list font set for placed texts.
• text place string - Set the string id to use for a placed text or list used string id for placed texts.
• text repeat move - Define a placed text as rolling text and set parameters or list rolling text parameters for placed texts.
• text rgb - Set colour for placed text or list colour values for placed texts.
• text rotation - Set rotation for placed text or list rotation values for placed texts.
• text scale - Set scale for placed text or list scale values for placed texts.
• text string - Define a string to be used for a placed text or list defined strings.
• text string concat - Concatenate two strings possibly into a third string

Syntax Overview

text align [<place id> (left | center | right) (top | middle | bottom) [<rotation>]
text alpha [<place id> <alpha>]
text anchor [<place id> (n | s | e | w | c | ne | nw | se | sw)]
text backgr [<place id> [ <l_pad> <r_pad> <t_pad> <b_pad> [<red> <green> <blue> <alpha>]]]  // <place id> only deletes backgr entry
text backgr alpha [<place id> <alpha>]
text backgr clip [<place id> <clip left> <clip right> <clip top> <clip bottom>]
text backgr linpat [<place_id> [<fraction> <red> <green> <blue> <alpha>] [ v | h]]
text backgr move alpha [<place id> <delta alpha> <alpha steps>]
text backgr move clip [<place id> <delta left> <delta right> <delta top> <delta bottom> <left steps> <right steps> <top steps> <bottom steps>]
text backgr rgb [<place id> [ <red> <green> blue> [ <alpha> ] ] 
text backgr round [<place id> <left top> <right top> <left bottom> <right bottom>]
text backgr [<place id> [ <l_pad> <r_pad> <t_pad> <b_pad> [<red> <green> <blue> <alpha>]]]  // <place id> only deletes backgr entry
text clip [<place id> <clip left> <clip right> <clip top> <clip bottom>]
text clipabs [<place id> <clip x> <clip y> <clip width> <clip height>]
text coor [<place_id> <x> <y>]
text font [<font id> [<font description>]]
text font available
text overlay (<place id> | <place id>..<place id> | all | end | <place id>..end) [ ... ] 
text place font [<place id> <font id>]
text place string [<place id> <string id>]
text grow <place id> <start len> [<delta grow> [variable]]
text move alpha [<place id> <delta_alpha> <step_alpha>]
text move clip [<place id> <delta left> <delta right> <delta top> <delta bottom> <left steps> <right steps> <top steps> <bottom steps>]
text move coor [<place id> [<delta_x> <delta_y> <step_x> <step_y>]]
text move rotation [<place id> <delta_rotation> <step_rotation>]
text move scale [<place id> <delta_scale_x> <delta_scale_y> <step_x> <step_y>]
text offset [<place id> <offset x> <offset y>]
text place [<place id> [<string_id> <font_id> <x> <y> [<red> <green> <blue> [<alpha> [(n | s | e | w | c | ne | nw | se | sw)]]]]]
text repeat move [<place id> <dx> <dy> <end x> <end y>]
text rgb [<place id> <red> <green> <blue>]
text rotation [<place id> <rotation>]
text scale [<place id> <scale_x> <scale_y>]
text string [<string id> [<string>]]
text string concat <dest string id> <string id> [<string id> ...]
text verbose [<verbose level>]
text help

---

The schematic below shows how a text is placed, how its background padding geometries are defined, how the rotation offset point is defined and an example of round corners for the text background for the right corners.

Commands

text align

Name

text align - Set horizontal and/or vertical alignment of a placed text or list alignment of placed texts.

Synopsis

text align [<place id> [(left | center | right) (top | middle | bottom)]

Description

The text align command is used to set or list the vertical and/or horizontal alignment for a placed text. The argument place id identifies the placed text to set the alignment for. Used without arguments, the command lists the alignment for placed texts. Used with just the place id argument, the function currently does nothing. When used with the place id argument and one or more of the alignment keywords, the placement of the text is aligned accordingly. The default value for a placed text is left and top.

When a placed text is overlayed, the bounding box of the text is aligned to the placed text's coordinates according to the alignment specified. The bounding box is an imaginary rectangle confining the text. The table below lists how the placed text's bounding box is aligned.

Alignment	Mode	Explanation
left	Hor.	The left side of the placed text is aligned to its coordinates.
center	Hor.	The vertical center of the placed text is aligned to its coordinates.
right	Hor.	The right side of the placed text is aligned to its coordinates.
top	Ver.	The top side of the placed text is aligned to its coordinates.
middle	Ver.	The middle horizontal wise of the placed text is aligned to its coordinates.
bottom	Ver.	The bottom side of the placed text is aligned to its coordinates.

Example

    text align 1 left top
    text align 1 center bottom
    text align 1 middle right
    text align 1 center
    text align

In the first example, the bounding box of the placed text will align its left-top corner with the coordinate specified for the placed text. In the second example, the text's bounding box's bottom and vertical center is aligned with the coordinate specified for the placed text. In the third example, the boudning box's horizontal middle and right side is aligned to the coordinate for the placed text. In the fourth example, only the vertical alignment is set. The horizontal alignment is left unchanged.

See also
text align, text clip, text coor, text place, text move alpha, text move clip, text move coor, text move offset, text move rotation, text move scale, text overlay, text rotation, text scale, text place font, text place string

---

text alpha

Name

text alpha - Set the alpha value for a placed text or list alpha value for placed texts.

Synopsis

text alpha [<place id> <alpha>]

Description

The text alpha command is used to set the alpha value for a placed text placed with the command text place. When used without any arguments, it will list alpha values for all placed texts. The argument place id identifies the placed text to set the alpha value for. Alpha values are integer or decimal values between 0 and 1. Values given for alpha less than 0 or greater than 1 are silently set to 0 or 1 respectively. The alpha value determines "how strong" a placed text is overlayed when overlayed. An alpha value of 1 means the virtual feed will be overlayed solidly. The closer the alpha value is to zero, the more transparent the overlayed text will appear. The default alpha value for a placed text is 1.0.

Example

    text alpha 3 0.4
    text alpha

See also
text align, text clip, text coor, text place, text move alpha, text move clip, text move coor, text move offset, text move rotation, text move scale, text overlay, text rotation, text scale, text place font, text place string.

---

text anchor

Name

text anchor - Set or list anchor the placed text.

Synopsis

text anchor [<place id> ( n | s | e | w | c | ne | nw | se | sw )]

Description

The text anchor command is used to set the anchor value for a placed text placed with the command text place. When used without any arguments, it will list anchor values for all placed texts. The argument place id identifies the placed to set the anchor value for. Setting an anchor for a placed text will have the effect that a coordinate pair will be added to the coordinate of the placed text when overlayed. The effect is that with the anchor option, placement of a placed text can be relative to the left or right, top or bottom or center of the system frame upon which the placed is being mixed into or overlayed on-top of. The default anchor for a placed text is nc. The table below list which the coordinate pair that will be added for a given anchor option. The width and height referenced in the table are the width and height set with the command system geometry

Option	Name	Coordinate pair to add
n	north	width/2, 0
s	south	width/2, height
e	east	width , height/2
w	west	0 , height/2
c	center	width/2, height/2
ne	north-east	width, 0
nw	north-west	0, 0 (default)
se	south-east	width, height
sw	south-west	0, height

Example

    text anchor 3 se
    text anchor

See also
text align, text clip, text coor, text place, text move alpha, text move clip, text move coor, text move offset, text move rotation, text move scale, text overlay, text rotation, text scale, text place font, text place string.

---

text backgr

Name

text backgr - Set/remove background for placed text or list values for background for placed texts.

Synopsis

text backgr [<place id> [<l_pad> <r_pad> <t_pad> <b_pad> [<red> <green> <blue> <alpha>]]]

Description

The text backgr command is used to set or remove a background for placed text identified by the argument place id. By default a placed text does not have its background enabled. Used without arguments at all, the command will list background settings for placed texts. Used with just the place id argument, the command will remove the background settings if any. If the command is given the arguments for padding as well, a background is defined for the placed text using the padding arguments. The padding arguments defines the integer number of pixels to pad around the placed text's bounding box as shown below:

Argument	Name	Explanation
l_pad	left padding	Number of padding pixels to the left of the text's bounding box
r_pad	right padding	Number of padding pixels to the right of the text's bounding box
t_pad	top padding	Number of padding pixels at the top of the text's bounding box
b_pad	bottom padding	Number of padding pixels at the bottom of the text's bounding box

The padding arguments can be negative as well as positive and 0. The padding size for a placed text will not change size if the placed text is scaled.

The default colour of the background for the placed text is black. The colour for the placed background can be set another color using the colour arguments red, green and blue which are decimal numbers between 0 and 1 describing the colour desired. The last optional argument is the alpha of the background of the placed text. The alpha value is a decimal number between 0 and 1. The default alpha value for a background for a placed text is 1.0 being solid. The closer the alpha value is to 0, the more transparent the background will appear. Snowmix offers a range of commands for manipulating the settings of a placed text's background.

Example

    text backgr 2 10 5 2 4 1.0 1.0 1.0 0.5
    text backgr 2 10 5 2 4 1.0 1.0 1.0
    text backgr 2 10 5 2 4
    text backgr 2
    text backgr

The first example defines a white background for placed text 2 with a left-right-top-bottom-padding of 10, 5, 2 and 4 pixels. The alpha of the background is set to 0.5 which is semi transparent. The second example does the same as the first example, except the background will set the alpha to the default value of 1.0. The third example does the same as example 2, but the background colour is set to its default value black or rgb=0,0,0. The fourth example will delete the background settings for the placed text. The fifth example list background settings for all placed texts.

See also
text align, text clip, text coor, text place, text move alpha, text move clip, text move coor, text move offset, text move rotation, text move scale, text overlay, text rotation, text scale, text place font, text place string.

---

text backgr alpha, text backgr clip, text backgr linpat, text backgr round, text backgr rgb

Name

text backgr alpha - Set alpha for background for placed text or list alpha value for background for placed texts.
text backgr clip - Set clip parameters for background for placed text or list clip parameters for background for placed texts.
text backgr linpat - Define a linear pattern set for background for placed text or list values for linear pattern sets for background for placed texts.
text backgr rgb - Set colour and optional alpha for background for placed text or list colour and alpha for background for placed texts.
text backgr round - Set round or rectangle corners for background for placed text or list values for corners of background for placed text.

Synopsis

text backgr alpha [<place id> <alpha>]
text backgr clip [<place id> <clip left> <clip right> <clip top> <clip bottom>]
text backgr linpat [<place id> [<fraction> <red> <green> <blue> <alpha>] [v | h]
text backgr rgb [<place id> [&ltred> <green> <blue> [<alpha>]]]
text backgr round [<place id> &ltleft top> <right top> <left bottom> <right bottom>]

Description

The argument place id identifies the placed text for which to set/change values for.

The text backgr alpha command is used to set the alpha value for a placed text's background or list alpha values for all placed text's background. The alpha value of the background of a placed text is a decimal number between 0 and 1, where 1 will result in a solid background and 0 will make it invisible.

The text backgr clip command is used to set the clip values for a placed text's background or list these values for all placed text. Only the part of the backbground within a specified ractangle is overlayed. The rest is "clipped" away. The arguments values for clipping are decimal numbers between 0 and 1. The clip left value defines how much to "clip" away from left where 0 is nothing and 1 is everything. The same applies to the clip top value, but seen from the top and down. The clip right value defines how far from left to start "clip" away where 0 is everything and 1 is nothing. The same applies to the clip bottom value, but seen from the top and down. If the left and right or the top and bottom clipping values sum is 1, everything is clipped away. If the sum is larger than 1, a negative box may be produced resulting in the same result as if the box was positive. If the clip left value is 0.65 and the clip right value we have the left clipping value is larger than the right clipping and we have 0.4-0.65 = -0.25. This is equivalent to setting the left value to 0.4 and the right value to 0.65. If this is confusing, make sure the sum of left and right and the sum of top and bottom does not exceed 1. Clipping the background of a placed text does not affect the placement of the text or in any other way affect the displayed text. It only affects the background of the placed text.

The text backgr linpat command is used to set the linear pattern values for a placed text's background or list linear pattern values for all placed text's background. A linear pattern background consist of a number of data sets defined by a decimal number for the fraction of the whole background, from 0 to 1 from left to right or top to bottom, a RGB set and an alpha value as well as a vertical or horizontal indicator. If the indicator is omitted in the command, horizontal is assumed as default. The example below list a a linear pattern with five data sets:

    text backgr linpat 1 0.0 0 0 0 0 h
    text backgr linpat 1 0.1 0 0 0 1 h
    text backgr linpat 1 0.5 1.0 1.0 1.0 1.0 h
    text backgr linpat 1 0.9 0 0 0 1 h
    text backgr linpat 1 1.0 0 0 0 0 h

Here we define a linear pattern background for placed text id 1. It has 5 data sets and they define a horizontal linear pattern. The first line defines that the linear patterns starts at the left side because the fraction of the whole is set to 0. It also defines that the pattern starts as black, 0,0,0 and that the alpha value of the background starts as invisible 0. The next line defines at 0.1 or 10% percent from the left, the background pattern is still black, but now the alpha value is 1.0 which is solid. Anything in between is defined as a linear approximation of these two definitions. The next line defines that at 0.5 or 50% from left, the pattern is now white, 0,0,0 and still solid. Again anything in-between the second and the third definition is a linear approximation of the second and the third definition. The fourth line is identical to the second line, but for a position at 0.9 or 90% of the background from the left. And the fifth data set defines the settings for the background at the right side. If the data set were to define a vertical linear pattern, the 0 or 0% is at the top and 1 or 100% is at the bottom. If a placed text's background has defined both a horizontal and a vertical pattern, the vertical pattern will win. Using the command text backgr linpat with just the place id argument, deletes all linear pattern data sets for the specified placed text.

The text backgr rgb command is used to set the colour values for a placed text's background or list colour values for all placed text's background. The argument values for setting the background colour define a colour and optional an alpha value. The colour values are 3 decimal numbers between 0 and 1 defining a colour and the optional alpha value is a decimal value between 0 and 1. If the alpha value is omitted, the alpha value for the background of the placed text is left unchanged. If the command text backgr rgb is used without any arguments, it will list colour values for the background for all placed text.

The text backgr round command is used to set the radius values for the corners of a placed text's background or list corner values for all placed text's background. The argument values for setting round corners for the background of placed text is the radius in pixels of each corner. A radius of 0 will result in a 90 degree corner instead of a rounding. The radius values are positive integers greater than or equal to 0. Using the command text background round will list the round corner values for all placed text.

Example

    text backgr alpha 2 0.3
    text backgr alpha
    text backgr clip 2 0 0.5 0 1
    text backgr clip
    text backgr round 2 5 10 0 0
    text backgr round

The first example sets the alpha value for the background of the placed text id 2 to 0.3. The second example lists alpha values for background for all text.
The third example clips away the background from 0.5=50% from left and everything thereafter. There is no clipping in the top or bottom. The fourth example list clipping values for the background for all placed text.
The fifth example sets radius in the top left corner of the background of placed text place id 2 to 5 pixels and the right corner to have a radius of 10 pixels. The two bottom corners are set to right angles.

See also
text align, text clip, text coor, text place, text move alpha, text move clip, text move coor, text move offset, text move rotation, text move scale, text overlay, text rotation, text scale, text place font, text place string.

---

text clip

Name

text clip - Set relative clip parameters for placed text or list relative clip parameters for placed texts.
Synopsis

text clip [<place id> <clip left> <clip right> <clip top> <clip bottom>]

Description

The text clip command is used to set the clip values for a placed text or list these values for all placed text. Clipping means here, that only the part of the text within a rectangle is overlayed. The rest is "clipped" away.

The argument place id identifies the placed text for which to set/change values for.

The arguments values for clipping are decimal numbers between 0 and 1. The clip left value defines how much to "clip" away from left where 0 is nothing and 1 is everything. The same applies to the clip top value, but seen from the top and down. The clip right value defines how far from left to start "clip" away where 0 is everything and 1 is nothing. The same applies to the clip bottom value, but seen from the top and down. If the left and right or the top and bottom clipping values sum is 1, everything is clipped away. If the sum is larger than 1, a negative box may be produced resulting in the same result as if the box was positive. If the clip left value is 0.65 and the clip right value we have the left clipping value is larger than the right clipping and we have 0.4-0.65 = -0.25. This is equivalent to setting the left value to 0.4 and the right value to 0.65. If this is confusing, make sure the sum of left and right and the sum of top and bottom does not exceed 1.

Clipping text does not affect the placement of a placed text.

Example

    text clip 1 0.2 1.0 0.0 1.0
    text clip

The first example clips away the left first 20% of the placed text. The second example list clip values for all placed texts.

See also
text align, text clip, text coor, text place, text move alpha, text move clip, text move coor, text move offset, text move rotation, text move scale, text overlay, text rotation, text scale, text place font, text place string.

---

text clip

Name

text clipabs - Set absolute clip parameters for placed text or list absolute clip parameters for placed texts.

Synopsis

text clipabs [<place id> <clip x> <clip y> <clip width> <clip height>]

Description

The text clipabs command is used to set the absolute clip values for a placed text or list these values for all placed text. Clipping means here defining a rectangle absolute placed on the mixer frame. Only the part of a placed text and possibly its background that is within the rectangle is overlayed and the rest is "clipped" away.

The argument place id identifies the placed text for which to set/change values for.

The arguments values for absolute clipping are pixel coordinates for the rectangle and width and height in pixels of the rectangle. The coordinate pair defines the placement of the top left corner of the rectangle. A placed text can have an absolute clipping as well as a relative clipping of both text and background.

Example

    text clipabs 1 200 150 400 100
    text clipabs

The first example defines that when overlaying placed text id 1, then only the part of the placed text that falls within a rectangle with the geometry 400x100 and placed at 200,150 is overlayed. The second example list the absolute clipping values for all placed text.

See also
text align, text clip, text coor, text place, text move alpha, text move clip, text move coor, text move offset, text move rotation, text move scale, text overlay, text rotation, text scale, text place font, text place string.

---

UNDER CONSTRUCTION

text backgr move alpha - Set animation value for alpha for background for placed text or list values for animation for alpha for background for placed texts.
- text backgr move clip - Set animation value for clip for background for placed text or list values for animation for clip for background for placed texts.