Animatroller Tools

This documentation is for the tools that can be used to manipulate recordings (capture-files) for the DMXking products.

Prerequisite

These tools are built with .NET Core 3.1. They have been tested on Windows, but should work on Linux and MacOS as well. You need to install .NET Core 3.1 runtime if you don't already have it. It's available here: .NET Core Runtime.

Background

Some of the DMXking products (like LeDMX4, eDMX2, eDMX4, etc) allow users to record and playback DMX content from an optional SD card located on the product. This allows for standalone playback among other things. The files on the SD card are basically Wireshark capture with captures data using either the ArtNet or sACN protocols. Wireshark can be used to view the capture files. One of the tricky parts with these capture files (recordings) is when it comes to creating seamless looping content. There is an advanced feature in the DMXking products that can use a separate channel to control recording, but it can be hard to use this easily in various lighting/video software. Because of that we have developed some simple command line tools that can manipulate the capture files on a computer. Once that's done then the files can be transferred back to the SD card (either by physically putting it in a computer, or using TFTP directly to the DMXking product).

Tools

The tools in the suite consist of:

• DMX Player - Playback of capture files over sACN (it can read ArtNet files as well though)
• DMX Recorder - Multi-universe recorder for recording content sent over the network
• PostProcessor - Tool to manipulate existing capture files

DMX Player

This tools takes a capture file as a command line input and plays it back over the network as sACN data. It can read sACN and ArtNet capture files (but it will always send data as sACN over the network). It can do looped playback and supports multiple universes. Sample command line parameters:

DMXPlayer -i "show001.cap" -f PCapArtNet -bo -l -1

What this does is using show001.cap as an input file, it specifies that it uses PCapArtNet as file format (PCap is the file format DMXking recordings and Wireshark is using, and ArtNet says that it contains ArtNet packets). Currently it doesn't auto-detect the protocol in the capture file. -bo means Black Out at end, which will set all channels to 0 at the end of the file (or when aborted with Ctrl-C). l -1 means loop the content forever (any positive number will loop that many times instead). If you just execute DMXPlayer.exe without any parameters then you'll see all the available command options. Example execution:

Network interfaces
vEthernet (Default Switch) - 172.21.64.1
Ethernet Dock - 192.168.240.150
vEthernet (WSL) - 172.27.80.1
ACN binding to 192.168.240.150
Playing back...
00:00:02.970 Played back 100 frames
00:00:05.972 Played back 200 frames
00:00:08.971 Played back 300 frames
Playback complete 10.8 s, 362 frames, iteration 1
00:00:02.970 Played back 100 frames
00:00:05.972 Played back 200 frames

There are also more advanced features like mapping input/output universes. More documentation coming soon.

DMX Recorder

This utility can be used to record sACN/E1.31 or ArtNet from multiple universes into a capture file. Example command line:

DMXRecorder -t sACN -o show001.cap -f PCapAcn -u 1,2 The above command will record sACN for universes 1 and 2 and store it into a capture file in the sACN format called show001.cap. More documentation to come later.

Post Processor

This utility is used to analyze and manipulate existing capture files for later playback on or off DMXking devices. To trim out the black (all channels 0%) at start and end of file:

PostProcessor -i show001.cap -if PCapArtNet -o show001_proc.cap -of PCapArtNet -c TrimBlack

This command takes an input file (show001.cap) in the PCapArtNet format. It will output to a file called show001_proc.cap in the same format. It will execute the TrimBlack command. It will then analyze the file and write the result to the output file.

1345 frames in input file
1144 frames written to output file

The next feature you'll use is to find the potential loop points. It will always start with the first frame (therefor it's good to start with the Trim command above) and then find a good loop point based on that. See this example command:

PostProcessor -i show001_proc.cap -if PCapArtNet -c FindLoop

Note how we used the previous output file (show001_proc.cap) as input to the FindLoop command. The output will look like this:

Position:  89.3%   Match: 100.00%   TrimPos: 1200
Position:  74.4%   Match: 100.00%   TrimPos: 1000
Position:  59.5%   Match: 100.00%   TrimPos: 800
Position:  44.6%   Match: 100.00%   TrimPos: 600
Position:  29.8%   Match: 100.00%   TrimPos: 400
Position:  14.9%   Match: 100.00%   TrimPos: 200
Position:  89.4%   Match:  98.33%   TrimPos: 1201
Position:  74.5%   Match:  98.33%   TrimPos: 1001
Position:  59.6%   Match:  98.33%   TrimPos: 801
Position:  44.7%   Match:  98.33%   TrimPos: 601

The output is sorted based on best match and position in the file where the trim position is found. What the output above means that the best match was at position 89.3% of the file (at frame 1200) and it was a perfect match (100%). It means if we trim at this position we will have a seamless loop. Note how this command doesn't have an output file, it will only analyze, not do the actual trimming (since you have to select where you want it to trim based on the output).

The final command is to do the trimming, here's the example command:

PostProcessor -i show001_proc.cap -if PCapArtNet -o show001_proc2.cap -of PCapArtNet -c TrimEnd -tp 1200

This will take the previous trimmed file (show001_proc.cap) and output show001_proc2.cap with the end trimmed at position 1200 (see above from the FindLoop command). You can now take this file and test it in the DMXPlayer with a loop parameter (-l 5) and verify that it looks good. Otherwise you can try a different trim position and re-test. Once good you can transfer the output capture file to the DMXking SD card. The command to do that is:

tftp -i 192.168.240.57 PUT show001_proc2.cap show001.cap

See the DMXking recorder manual for how to do looping shows, but basically you'll put a file called show001.txt that has a single line like this:

show001

Which will then loop itself forever.