OBS Overlays for Twitch Streaming

Abbreviate the input string to given width if it exceeds a maxium width. If only a maximum width is given, abbreviated and maximum width are the same. The first parameter is the maximum width, the optional second parameter the abbreviated width.

You can control where the abbreviation happens by putting an abbr-left, abbr-middle, or abbr-right filter before the abbreviate filter. You can also use something other than …​ as the abbreviation indicator by putting and abbr-ellipsis filter with an argument containing the indicator you want to use in front of the abbreviate filter. These special abbr- filters can only be used just before an abbreviate filter.

Adds the value and all the filter’s arguments together. If they are all numbers, calculates their sums. If any is a non-numeric string, concatenates the arguments. There are also multiply and divide filters which take only a single argument, and perform the corresponding arithmetic operation on the value (they only work with numbers).

count counts the letters in a string, or the number of elements in a collection (such as the players). count-is checks whether that count matches its argument. You can use it with the if tag to conditionally display content if there are a certain number of players on the network, for example:

Allows you to specify a value to display when a variable is empty or missing. Normally, in such situations the variable just disappears from the template (it is replaced by an empty string). If there is no track loaded on player 2, this expression will result in the string No track:

Notice that we had to quote the filter’s argument because our value had a space in it.

Rounds a number to a specified number of decimal places. This is useful when working with pitch values, since we usually only want two places after the decimal point:

There is also a round filter which rounds all the way to the nearest integer, and number-format which lets you use a Java format string to get full control of the way you format the number, even specifying an ISO-639 two-letter locale specifier as its second argument.

Check whether the specified value is empty or not (both filters return true or false). These are again useful combined with the if tag to conditionally render content:

Convert a value to lower-case.

Convert a value to upper-case. (There are also two variants: capitalize converts only the first character to upper-case, while title converts the first letter of each word to upper-case.)

Takes two string arguments, and replaces any instances of the first string found in the value with the second string.

Sorts the elements of the value. You will generally want to apply this filter when you are looping over the values in players because they are otherwise not going to necessarily be in numerical order.

Conditionally renders the body only if the argument is true.

You can reverse the meaning of the conditional argument by preceding it with the not operator, or combine multiple conditional arguments with the all or any operators. You can also perform numeric comparisons using the =, <, >, <=, and >= operators, or string comparison using =.

(Notice that the above example shows that filters can be applied to the conditions.)

In addition to the if, else and endif tags, you can have as many elif tags as you need between the else and endif, meaning “else if”. For more examples, see the Selmer documentation.

Loops over each item in an array or map, making the item available in a variable of your choice inside the loop. Beat Link Trigger uses nested maps rather than arrays for its template parameters, and you can loop over entries in the map assigning the key and value of each entry to separate variables:

The above example loops over all the players that are found on the network. Each time through the loop, number is set to the channel number of the player and player is set to the map of parameters describing the state of that player, so the loop outputs a paragraph for each player, showing the channel number, a colon, the title of the track being played on that player, and the artist that recorded it.

Notice that the body of the loop is ended by an endfor tag, and that we were able to use the sort filter on the players map to make sure we got them in order of increasing channel number.

After the endfor tag, the number and player variables introduced by the loop go away.

You can also place an empty tag between for and endfor, and the content within that section will be rendered if the variable you were trying to loop over had no values:

In addition to the variables you requested, the for tag always adds several others that allow you to respond to or display additional information about the looping process:

Picks the next value from a list of values each time through a loop. Here is an example of this tag combined with the for tag to create a list item for the player number and track title of each player found on the network, and alternating the CSS classes of each between blue and white:

Replaces itself with the contents of the referenced template.

Specifies a block of content that can be overwritten using template inheritance.

This tag is used to reference a parent template, which provides the outer structure that gets rendered. The blocks in the parent are recursively overridden by the blocks from child templates, using template inheritance.

You can look up the album art for the track loaded in a particular player using a URL like /art/1 (replace the 1 with another number to get the art for the player on a different channel). If there is artwork, this will return an 80x80 pixel JPEG image. If there is no art, or no track loaded, it will return an 80x80 transparent PNG image.

If you would like to display more information about why there is no artwork, the way Beat Link Trigger does, you can add a query string to the request: /art/3?icons=true. With icons set to true, when the art is missing, you will receive a PNG image that describes why. If there is no track loaded, it will read "No Track". Otherwise, it will be an icon describing where the track was loaded from: USB, SD, CD Digital Audio, CD Data, or rekordbox.

You can access the whole-waveform preview (as is displayed at the bottom of a CDJ screen) for the track loaded on a particular player using a URL like /wave-preview/2. If you request it that way, it will be rendered at a default width and height, but you can specify the size you want using query parameters:

This image will show the current playback position of the player as a bar moving along the image, and will have small triangles marking hot cues and memory points.

If there is no waveform available for the specified player, a transparent image will be returned.

You can access the scrolling detailed waveform (as is displayed at the top of a CDJ screen) for the track loaded on a particular player using a URL like /wave-detail/4. If you request it that way, it will be rendered at a default width and height, but you can request a specific width and height using query parameters like with the waveform preview. You can also control the scale (zoom level) with which the waveform is rendered. The default scale is 4, meaning each column of the image is an average of four half-frames of audio. Setting scale to 1 shows the full detail available, while larger values let you see more of the waveform at once.

The image will show the current playback position of the player as a bar centered in the image, and the waveform will scroll as playback occurs. Hot cues and memory points will be drawn (including their labels and if they have been assigned), and loops will be visible.

If there is no waveform available for the specified player, a transparent image will be returned.

As noted above, if you are creating an overlay with a light background, you might want to change the waveform background color.