vapoursynth-faveworm 2

Analog oscilloscope emulation

Faveworm: analog oscilloscope emulation

Plug-in for the Vapoursynth and Avisynth+ video processor engines.

Faveworm tries to mimic the rendering of an analog oscilloscope to display audio waveforms. It aims at building a realistic beam trace, thin and darker when the beam travels quickly, thick and bright when it moves slowly. Features like phosphor persistence or bloom effects are not part of this plug-in and left to an optional post-processing step.

It supports x86 and Arm architectures, for Windows and Linux, in 32 and 64 bits.

Output in trigger mode with waveform locking. Video: 30 fps, audio: 48 kHz, sweep time: 20 ms

Post-processed output

Scrolling mode, post-processed output. Display: 5 s

X-Y mode, post-processed output

Installation

Windows / x86

In a 64-bit environment, from VapourSynth r74, the Faveworm plug-in can be installed with the following command:

pip install vapoursynth-faveworm

Otherwise you can just unpack the dll from the Win64 or Win32 directory from the archive and copy it to your plug-in folder.

Other platforms

You’ll have to compile the library from the source (see below) and copy it to the plug-in folder.

Compilation

Windows

• Open faveworm\build\win\faveworm.sln in Visual Studio.
• Menu Build -> Configuration Manager, select the desired configuration (most likely Release x64).
• Then go to Build -> Build Solution.

The dll is in the faveworm\(configuration)\ subdirectory.

For using it with Vapoursynth, copy the generated faveworm.dll to [user directoy]\AppData\Roaming\VapourSynth\plugins64.

For Avisynth+, copy this file to the [Program Files]\AviSynth+\plugins64+ directory.

Linux and MinGW

cd build/unix
./autogen.sh
./configure CXX='clang++' CC='clang'
make
make install

Clang is not mandatory but a bit faster than GCC.

Usage

Faveworm requires at least an audio clip, mono or stereo depending on the selected display mode.

The input video sets the framerate, size and properties, but the output format is always overridden to gray, 32-bit float and progressive. The signal is displayed on the whole frame on a black background (0). Because the output colorspace is in linear light, it requires an extra step to adjust the transfer curve to a more familiar gamma-compressed colorspace. The audio defines the length of the generated video. With the default gain, the frame borders correspond to an audio level of 0 dBFS.

Vapoursynth example

import vapoursynth as vs
core  = vs.core
video = core.std.BlankClip ()
audio = core.bas.Source ("audio.wav")
video = core.fw.scope (clip=video, audio=audio, mode=0, sweep=0.020, beam_size=1.5)
video = core.fmtc.transfer (video, transs="linear", transd="1886")
video.set_output (0)
audio.set_output (1)

Avisynth+ example

BlankClip ()
AudioDub (WavSource ("audio.wav"))
fw_scope (mode=0, sweep=0.020, beam_size=1.5)
fmtc_transfer (transs="linear", transd="1886")

Parameters

• clip: Input video. Its content is discarded and only its framerate, size and properties are used.

• audio: input audio whose waveform is drawn on the output video. It requires at least 1 channel. First (left) channel is mapped on the Y axis (vertical). When using the X-Y mode, the second one (right) is mapped on the X axis (horizontal). Channels can be remapped with y_chn and x_chn. This parameter is mandatory for Vapoursynth. With Avisynth, it is possible to use the audio part of clip.

• mode (0):

  • 0: Time mode with trigger. The waveform is displayed when the signal crosses the specified trig_thr threshold. This crossing is centered horizontally with x_ofs. When there is no crossing during a given period, the oscilloscope switches to free-running mode until a crossing is encountered again.
  • 1: Time mode, running free. The beam sweeps the screen regularly displaying the input waveform.
  • 2: Scrolling mode. This mode is unconventional for an analog oscilloscope but is pretty useful. It displays sweep seconds of audio on the whole screen, centered on x_ofs, on any frame.
  • 3: X-Y mode. This is a classic dual channel mode, using a second channel for the X horizontal position instead of time.

• shutter (1): Indicates the ratio of the frame duration during which the shutter of the virtual camera is open and capturing the picture. A value of 1 means open during the whole frame. Range: [0.001 ; 1].

• y_chn (0): Index of the audio channel containing the displayed signal (Y axis for the X-Y mode).

• y_gain (1): Linear gain to apply to the input signal (vertical scale) before displaying it. A negative value inverts the vertical axis.

• y_ofs (0): Constant value to add to the signal (after gain) to shift its vertical position. Positive values shift towards the top. 0 is neutral, 1 in absolute value is the top or bottom of the picture.

• beam_size: Average diameter in pixels of the beam, > 0. Default is 2, 1.5 is possibly the thinnest and sharpest beam before showing aliasing. Keep this value moderate (below 10) to avoid display artefacts when the beam is intense. The spot energy is scaled according to the beam size so the average energy density (per pixel) is kept constant. This makes the parameter more a scaling factor than a focus setting.

• beam_gain: Linear gain on the beam lightness (contrast setting). Should be greater or equal to 0, 1 is the standard value.

• x_ofs (0): In trigger and scrolling modes (0 and 2), this is the horizontal position in the frame of the reference event: -1 = left, 0 = center, +1 = right. In X-Y mode (3), this is a constant value to add to the signal (after gain) to shift its horizontal position. 0 is neutral, 1 in absolute value is the left or right border of the picture.

This parameter is used only in time modes (0–2):

• sweep (0.010): Time in seconds during which the beam travels through the screen from left to right. In scrolling mode (2), it indicates the signal view duration.

The following parameters are used only in trigger mode (0):

• trig_thr (0): Signal threshold for the trigger (before amplification with y_gain).

• trig_dt (0): Time in seconds after a sweep before doing a search for the next trigger. This can be negative to trigger a new sweep even if the current one is not finished. In this case the first one will terminate as usual, possibly duplicating displayed data. Must be greater than minus sweep.

• trig_down (False): Direction of the threshold crossing to trig a sweep. False or 0: up (positive), True or 1: down (negative)

• trig_lock (False): When set to True, the display tries to lock on a waveform using autocorrelation. Several threshold crossings are tested during an analysis period, and the best match is selected at the end. This helps stabilizing the waveform, at the expense of an additional display latency, and possibly a shimmering waveform if the signal doesn’t show a good self-similarity.

The following parameters are used only in X-Y mode (3):

• x_chn (1): Index of the audio channel containing the displayed signal (Y axis for the X-Y mode).

• x_gain (1): Linear gain to apply to the second channel of the input signal (horizontal scale) before displaying it.