Since build 5.2.1009 it is possible to to configure custom mixer layout with a special XML-based language. In this case, no need to develop custom Java class.
Custom mixer layout is a set of XML files with .mix extension placed in the same folder. Every file should describe layout for a certain number of participants: 1, 2, 3, 4 etc. File name should start from participants number followed by understrike character, the rest of file name should contain various alphanumeric characters, for example
One mixer layout description files should be placed in one folder. One participans count should be described by one, and only one, file. Mixing of two layouts in the same folder is not allowed.
A full path to mixer layout folder may be set with the following parameter in flashphoner.properties file
In this case, the layout will be applied by default to all the mixers on the server.
Also, the path to mixer layout folder can be passed in REST API query /mixer/startup:
Applying a custom layout to an active mixer on the fly
Since build 5.2.1480, a custom mixer layout may be applied to an active mixer on the fly
To roll back to default mixer layout set the empty
In this case, a mixer layout class set in
mixerLayoutClass parameter will be applied.
Layout description file format
Layout description XML file must conform tho the following XSD scheme
All the layout descriptors are validated by this scheme, if validation fails for some descriptor, standard layout will be used for its participants count.
The following elements are supported:
- body - a root container to place all the pictures descriptions, repersenting mixer canvas. May be used once per file
- div - container to place one picture, a set of pictures or another container. May be used in any quantity per file, can also be nested
- video - a picture description, representing a stream in mixer. May be used in any quantity per file.
The body element is a root container for all the children elements. The following attributes are supported:
- watermark - a picture file name to applt=y as watermark to whole mixer output stream (since build 5.2.1051)
The div element is a container for other div or video elements. The following attributes are supported:
- x, y - left top corner coordinates on mixer canvas in pixels
- width - width on mixer canvas in pixels or parent element width percents
- height - height on mixer canvas in pixels or parent element height percents
- padding-left, padding-right, padding-top, padding-bottom - padding from corresponding side in pixels
- align - align on mixer canvas or in parent container
align attribute supports the following possible values
- LEFT - element is left aligned
- RIGHT - element is right aligned
- TOP - element is top aligned
- BOTTOM - element is bottom aligned
- CENTER - element is centered
- BOTTOM_CENTER - element is centered and bottom aligned
- TOP_CENTER - element is centered and top aligned
- INLINE_HORIZONTAL - element is adjusted to right top corner of closest left element
- INLINE_HORIZONTAL_CENTER - the same as above, with vertical centering
- INLINE_VERTICAL - element is adjusted to left bottom corner of closest element above this one
- INLINE_VERTICAL_CENTER - the same as above, with horizontal centering
If left top corner coordinates are set explicitly, align attribute is not applied
Since build 5.2.1052 row element is supported to represent a row of one or more stream pictures. Supports the same attribuites as div
Represents stream picture in parent container. The same attributes are supported as div element, with additional attribute
- crop - crop a picture around the center
crop attribute may be true или false (by default).
Stream picture width
Since build 5.2.1052, a stream picture width can be set in pixels, parent element width percents, or in columns. This is supported for row element children only, for example
In this case, when parsing a custom layout descriptor, one column size is calculated as row width divided by cheild elements count of one level. Then all the child elements widths are set as columns count configured in width arrtibute.
The mixer output stream example for the descriptor above
It is not allowed to mix percents with columns in one level items!
Since build 5.2.1094, width may be set in columns for div child elements also.
Stream picture height
Since build 5.2.1094, stream picture height can be set in pixels, parent element height percents, or in rows
In this case, when parsing a custom layout descriptor, one row size is calculated as element height divided by child elements count of one level. Then all the child elements heights are set as rows count configured in height arrtibute.
The mixer output stream example for the descriptor above
It is not allowed to mix percents with rows in one level items!
Stream name template definition
A stream name template can be set in video element. For example
will display only stream named 'test', and will not be applied to any stream with other name.
The template can be set as regular expression, for example
In this case this element can display streams named test1, test1#room1, test11 etc
If the stream name does not meet any template in the file, and there is empty video element in the file, this element will be used for that stream. For example, here is a description for one participant
In this case test3 will be displayed in last video element
Whole mixer or participant stream watermarking
Since build 5.2.1051 it is possible to set PNG picture in custom layout descriptor, which will be applied as watermark to whole the mixer output stream or to a certain participant stream in mixer.
To apply watermark to the whole mixer output stream, add watermark attribute with relative PNG file name to body tag:
PNG file should be placed to the layout folder:
The example of mixer output stream with watermark applied
Watermark can be applied to a certain participant stream in mixer. To do this, add watermark attribute withPNG file name to video tag:
Screen sharing description for a certain number of participants
Since build 5.2.1091 it is possible to describe a custom desktop (screen sharing) layout for a certain number of participants. Desktop layout description files should have
.desktopmix extension and should be placed in the same folder as usual descriptors:
Desktop stream is detected by stream name template. This is the example descriptor for 2 participant streams and desktop stream
Note that desktop stream is the same stream as participants one at mixer point, so 2 participants
video elements and 1 desktop
video element are defined in 3 participants descriptor file in this case.
If there is no
*.desktopmix file foa a certain number of participants, and desktop stream is added to mixer, a standard desktop layout will be used.
Configuration errors handling
1. If the mixer layout contains no description file for a certain participants number, the layout class set in the following parameter will be applied
By default, GridLayout will be used
2. If stream name does not meet any template in description file for a current number of participants, audio and video from this stream will not be added to mixer output stream
Custom layout examples
Placing stream pictures according to stream names
Lets' create a custom mixer layout for 640x360 mixer stream up to three participants. Note that all the picture sizes are set explicitly, and should not exceed mixer canvas size.
One participant description:
Two participans description
Three participants description
The mixer with test1 stream output example
The mixer with test1 and test2 streams output example
The mixer with test1, test2, test3 streams output example
Placing stream pictures randomly without strict size limiting
One participant description:
Two participants description:
Three participants description:
One participant displaying
Two participants displaying
Three participant displaying
Custom layout displaying tool
Since build 5.2.1035 custom mixer layout displaying tool is added. The tool should be launched from command line
The tool writes mixer layout pictures to the folder defined, one PNG picture per one layout descriptor file
The following parameters are supported:
- /path/to/mixer_layout - path to layout folder, mandatory
- -o=/path/to/output - path to pictures output folder
- -n=1 - participants count to display a picture; if this is not set, pictures for all participants count will be written
- -N=test1,test2,test3 - stream names list to use for pictures rendering; if streams count in list is lower than participants count, automatically generated names will be used: stream0, stream1 etc
- -p=test - perfix to generate stream names; in this case, stream names wuill be generated subsequently, starting from 0, for example test0, test1, test2 etc
- -a - draw speech indicator frame around all the pictures
- -s=640:360 - mock participant picture size, equal to mixer picture size by default
- -h - shown the tool command line parameters list
The tool uses current mixer settings from flashphoner.properties file
Look at pictures displaying examples for the custom layout described above
1. The picture for one participant with speech indicator displaying, stream names are set explicitly
Output file /tmp/1_test.png
2. The picture for three participants, stream names are formed automatically with the prefix set
Output file /tmp/3_test.png
Stream names templates in this layout descriptors are set explicitly as
test3.*. When stream names are generated automatically, streams count starts from 0, therefore the following names were generated for this participants count:
test2. In this case, for missed stream
test3 name is displayed as
No stream for: test3.*
1. If one of the pictures size in custom layout descriptor exceeds mixer canvas size, the tool will display the following error message, and PNG file will not be generated:
If a mixer is created with such custom layout, the mixer will be closed with the same error message.
2. If there are no
*.desktopmix descriptors for a certain number of participants, the tool will generate a picture file with
_fallback suffix using a standard mixer layout from WCS settings.
Standard layouts implementation in XML markup language
The following archive file
Layouts.tar.gz contains examples of standard mixer layouts implementation compatible with WCS builds since 5.2.1094 and newer
The archive contains the following folders:
- GridLayout - grid layout implementation with paddings
- CenterNoPaddingGridLayout - grid layout implementation with no paddings between picture frames
- СropNoPaddingGridLayout - grid layout implementation with no paddings between picture frames and images crop
- samples - mixer output picture samples folder
1. Unpack the archive to /opt folder
2. Set default layout in flashphoner.properties file as needed
or set the layout while creating a mixer by REST API
"Picture-in-picture" custom layout implementation
To place one stream picture, for example, desktop translation, as a background for participants web cameras streams pictures, the
row tag containing desktop stream should be parent for
row tags with participants pictures, for example:
The sample custom picture in picture layout up to 10 participants + 1 desktop is in the archive file
A desktop stream should have a name with _
desktop suffix, for example