- Configuration language

Recording
Option Pose: recording, playback, copying, conversion

Show version changes

# Configuration language

When starting, the xposextool program reads configuration statements from the command line or from configuration files (Configuration file).

## Statement syntax

A configuration comprises one or more of the statements globalSettings (Global statements) recordSettings (Recording) playSettings (Playback), copySettings (Copying), andconvertSettings (Conversion). These statements contain nested sub-statements, sub-sub-statements, and sub-sub-sub-statements. If one of these statements is used on a higher level, it specifies a default value for the lower level parameters.

The configuration statements follow some general rules:

Words are separated by arbitrary white space characters. The line structure is irrelevant.

If a word contains white space characters, it has to be surrounded by double quote characters ". This special meaning of the double quote character is overridden by preceding it with a backslash character \.

Keywords are case-insensitive: the meanings of CopySettings and copysettings are identical.

Keywords are not reserved.

Most configuration statements consist of the name of a parameter and its new value. The name may be written with or without a directly following colon :.

In the case of multiple parameter definitions with the same name, only the last one is valid.

The succeding sections describe the configuration statements by a formal syntax using the following elements:

keywords have special meanings.

variable_input depends on the configuration.

alternative_1|alternative_2: Alternatives are separated by a vertical bar.

[optional]: Optional parameters are surrounded by brackets.

parameter...: Repetition (one or more times) is denoted by the ellipsis.

{element}: Braces are used for grouping.

## Default configuration

If the xposextool program is called without any arguments, the default configuration is effective. The following lines show almost all configuration statements with their default values

    recordSettings
        fromDisplay $DISPLAY
            connectTimeout "20 sec"
            offlineTimeout "0 ms"
            continueWhenOffline off
            transmission uncompressed
            multimedia record ""
            types input output
            clients all
            pointerMotionResolution 15
            timestampResolution 100
            showSnapshotPointerImage on
        toFile ~/%Y-%m-%d_%H:%M:%S.pose
        newFiles never
        overwriteProtection on
        keepNumberOfFiles 0
        insertSnapshot earliestAfter "60 min"
        encoding uncompressed
        title ""
        subTitle ""
        description ""
        keywords ""
        author ""
        copyright ""
        terminate never

    playSettings
        fromFile ""
        sortFiles off
        recordedDisplays all
            toDisplay $DISPLAY
                connectTimeout "20 sec"
                offlineTimeout "0 ms"
                displayMode fullscreen
                startHidden off
                onTop on
                suppressScreenSaver off
                title ""
                serverFonts off
                pointerZoom 1
                osd off osdX -800 osdY 0
                clipX 0 clipY 0 clipWidth 0 clipHeight 0
                displayX 0 displayY 0 displayWidth 0 displayHeight 0
                types output pointerMovements
        startTime begin +00:00:00
        stopTime end -00:00:00
        ignoreEOF on
        playMode wait
        speed 1.0 synchronous
        screenshotTo ~/%Y-%m-%d_%H:%M:%S.ppm
        hotKey suspend Control Space
        hotKey previousSnapshot Control Left
        hotKey nextSnapshot Control Right
        hotKey doubleSpeed Control KP_Add
        hotKey maxSpeed Control KP_Multiply
        hotKey halfSpeed Control KP_Subtract
        hotKey hundredthSpeed none
        hotKey thousandthSpeed none
        hotKey previousScreen Control Up
        hotKey nextScreen Control Down
        hotKey screenshot Control S

    copySettings
        fromDisplay $DISPLAY
            connectTimeout "20 sec"
            offlineTimeout "0 ms"
            continueWhenOffline off
            transmission uncompressed
            multimedia
                record ""
                feedback ""
            types input output
            clients all
            pointerMotionResolution 15
            toDisplay $DISPLAY
                connectTimeout "20 sec"
                offlineTimeout "0 ms"
                displayMode fullscreen
                startHidden off
                onTop on
                title ""
                serverFonts off
                pointerZoom 1
                osd off osdX -800 osdY 0
                clipX 0 clipY 0 clipWidth 0 clipHeight 0
                displayX 0 displayY 0 displayWidth 0 displayHeight 0
                types output pointerMovements
                inputSwitch off
                selectionSync off
        screenshotTo ~/%Y-%m-%d_%H:%M:%S.ppm
        hotKey suspend Control Space
        hotKey previousScreen Control Up
        hotKey nextScreen Control Down
        hotKey screenshot Control S

    convertSettings
        fromFile ""
        sortFiles off
        recordedDisplay :0.0
            toDisplay $DISPLAY
                connectTimeout "20 sec"
                offlineTimeout "0 ms"
                displayMode fullscreen
                suppressScreenSaver on
                serverFonts off
                pointerZoom 1
                clipX 0 clipY 0 clipWidth 0 clipHeight 0
                displayWidth 0 displayHeight 0
                types output pointerMovements
        startTime begin +00:00:00
        stopTime end -00:00:00
        toFile ~/converted.mpeg1
        encoder FFMPEG
        format "MPEG-1 Video"
        frameRate 24
        imageQuality 60
        ringBellWhenFinished on

    globalSettings
        hotKey gui Shift Control
        numberOfThreads 4
        logDestination /var/opt/XSOXmetaX/logs/xposextool-user_name.html
        logTypes errors statistics

## Comments

Comments start with a number symbol # and extend to the end of the line.

If a comment — after elimination of white space characters — starts at the beginning of a line, it is associated with the last preceding top level statement. When writing a configuration file, the configuration tool places these comment lines just between the corresponding top level statement and the following sub-statements.

The introducing comment lines preceding the first top level statement are preserved.

All other comments are ignored and not saved by the configuration tool.

## Variables

The environment variables are accessed like in a shell, for example:

    playSettings recordedDisplay $DISPLAY

Variable assignments, however, follow a different syntax:

    set variable_name value

like in:

    set POSEFILE $HOME/1.pose

A variable name begins with a letter (including the underscore _) followed by letters or digits. Braces are used to separate the variable name in special situations:

    set server1 remote:1.
    playSettings recordedDisplay ${server1}0

Each variable set in the configuration is copied into the environment where it may be accessed by, for instance, programs connected by the Multimedia mechanism (Multimedia) (Multimedia) (Converted file).

## Lists

Some statements take as argument a list of individual items in the form of:

    {[+|-]item}...

The optional sign determines whether an item is included or not: if an item specifier starts with a minus character -, then the corresponding item is deleted from the configured set of items, otherwise it is included into the set. The initial set depends on the first specifier: if it starts with a minus character -, the initial set contains all possible items, otherwise the initial set is empty.

## Arithmetic expressions

Arithmetic expressions may contain the operators *, /, and % (modulus), + and - as well as variable references. They are surrounded by parentheses, for instance:

    set width 1280
    set doubleWidth ($width * 2)

## Points of time and periods of time

The specification of a point of time follows an enhanced ISO syntax:

    [year{-|/}month{-|/}day] hours:minutes[:seconds[.milliseconds]] [am|AM|pm|PM] [Z|{+|-hours:minutes}]

The following examples denote nearly the same time on August 20, 2008 in Central Europe:

    2008-08-20 20:08:20.2008
    20:08
    18:08 Z
    08:08 pm

The syntax for the specification of a period of time is similar:

    [[hours:]minutes:]seconds[.milliseconds]

The following examples denote approximately the same period:

    1:23:45.678
    83:45
    5025

## File sizes

File sizes are specified using the known units (Bytes by default):

    number[{Bytes|Byte|B}|{KiB|KB|K}|{MiB|MB|M}|{GiB|GB|G}|{TiB|TB|T}]

In all cases the factors conform to the binary system, the following examples denote the same size:

    1024
    1024B
    "1024 bytes"
    1KiB
    1KB
    1K

## Configuration file

The statement

    source file_name|-

or, even shorter

    file_name|-

is substituted by the contents of a configuration file. The file name - stands for the standard input stream. The file inclusions may be nested arbitrarily, but not cyclically.

The statement

    stop

terminates the interpretation of a configuration file before reaching the end of the input. The remaining contents are neither read in nor saved by the configuration tool.

## Multimedia profiles

How the xposextool program has to control multimedia devices — like microphones, cameras, loudspeakers, serial lines — or external converters, is determined by multimedia profiles in the multimedia profiles file xmultimedia_profiles. Usually this file is stored in the installation directory /etc/opt/XSOXmetaX (Installation directories).

The profiles define key names for devices, programs, and parameters, which are referred by the following configuration statements or in the dialog box (XposeXtool: control and configuration with graphical user interface). More informations can be found in the multimedia profiles file.

Hereafter multimedia_specification denotes a list of key names from the multimedia profiles file or parameter assignments surrounded by double quotes ", like:

    "Microphone"
    "Microphone CD-quality"
    "Microphone CD-quality X_Audio_Input_Volume=100%"

    "FFMPEG"
    "MPEG-1 Video"

## Pattern elements

Some parameters may contain pattern elements which are substituted by current values at runtime.

The pattern elements are known from date(1) or strftime(3C) with the exception of the second (many substitutions depend on the selected locale):

Pattern element | Meaning
--- | ---
%% | same as %
%n | serial number of the file starting with 1
%a | abbreviated weekday name
%A | full weekday name
%b | abbreviated month name
%B | full month name
%c | locale's appropriate date and time representation
%C | century number [1,99]; single digits are preceded by 0
%d | day of month [1,31]; single digits are preceded by 0
%D | date as %m/%d/%y
%e | day of month [1,31]; single digits are preceded by a space
%F | equivalent to %Y-%m-%d (the ISO 8601 date format)
%G | The ISO 8601 week-based year with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead.
%g | like %G, but without century, that is, with a 2-digit year (00-99)
%h | abbreviated month name
%H | hour [0,23]; single digits are preceded by 0
%I | hour [1,12]; single digits are preceded by 0
%j | day number of year [1,366]; single digits are preceded by 0
%k | hour [0,23]; single digits are preceded by a blank
%l | hour [1,12]; single digits are preceded by a blank
%m | month number [1,12]; single digits are preceded by 0
%M | minute [00,59]
%p | locale's equivalent of either a.m. or p.m.
%r | appropriate time representation in 12-hour clock format with %p
%R | time as %H:%M
%s | the number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC)
%S | seconds [00,61]
%t | insert a tab
%T | time as %H:%M:%S
%u | weekday as a decimal number [1,7], with 1 representing Sunday
%U | week number of year as a decimal number [00,53], with Sunday as the first day of week 1
%V | week number of the year as a decimal number [01,53], with Monday as the first day of the week
%w | weekday as a decimal number [0,6], with 0 representing Sunday
%W | week number of year as a decimal number [00,53], with Monday as the first day of week 1
%x | appropriate date representation
%X | appropriate time representation
%y | year within century [00,99]
%Y | year, including the century (for example 1993)
%z | the +hhmm or -hhmm numeric timezone (that is, the hour and minute offset from UTC)
%Z | time zone name or abbreviation, or empty
%Ec | date and time representation in the alternate representation
%EC | name of the base year (period) in the alternate representation (for example 19)
%Ex | alternate date representation
%EX | alternate time representation
%Ey | offset from %EC (year only) in the alternate representation
%EY | full alternate year representation
%Od | day of the month using the alternate numeric symbols
%Oe | same as %Od
%OH | hour [0,23] using the alternate numeric symbols
%OI | hour [1,12] using the alternate numeric symbols
%Om | month using the alternate numeric symbols
%OM | minutes using the alternate numeric symbols
%OS | seconds using the alternate numeric symbols
%OU | week number of the year (Sunday as the first day of the week) using the alternate numeric symbols
%Ow | number of the weekday (0 for Sunday) using the alternate numeric symbols
%OW | week number of the year (Monday as the first day of the week) using the alternate numeric symbols
%Oy | year (offset from %C) in the alternate representation and using the alternate numeric symbols

top
Recording
Option Pose: recording, playback, copying, conversion

Copyright © 2016 X-Software GmbH
info@x-software.com
2016-01-20 12:06:44 +0100