muxsa/doc/howto.md

# MUXSA HOWTO

This is the step-by-step documentation how to use muxsa.  For an overview on muxsa please watch the [Demonstration video (a.k.a. the making of Network Security 2020)](https://nks-devel3.rus.uni-stuttgart.de/muxsa/making_of_netsec_2020.mp4) and keep the [muxsa block diagram](muxsa-blockdiagram.png) in mind.

The author uses muxsa with Debian Linux 11 ("bullseye").  The muxsa scripts
and the other software packages used are not very specific to this Linux
distribution, so muxsa should work with other distros as well. However, some
adjustments to path names or package names might be neccessary.

## Install dependencies on Linux

Install the prerequisites (here: on Debian Linux 11) with:

    apt-get install libvirt-clients spice-client-gtk imagemagick xdotool netpbm coreutils perl audacity ffmpeg 

## Create the PNG files from your presentation slides

### Install a Virtual Machine with Windows 10 and Powerpoint

The author uses muxsa on a computer with 8 CPU cores and 24 GiB RAM that runs
Debian Linux 11 (amd64).  In virt-manager, create a virtual machine with 4 CPU
cores, 16 GiB RAM, 80 GiB harddisk, display: spice, video: QXL, channel: spice. 

Install Windows 10 Enterprise 64bit. Install the spice-guest-tools
for Windows from [spice-space.org](https://www.spice-space.org/download/windows/spice-guest-tools/spice-guest-tools-latest.exe). 

Use spicy to access the virtual desktop of your virtual machine. For example,
if the name of your virtual machine is win10-office, use 

    spicy --uri="$(virsh -c qemu:///system "domdisplay win10-office")"

to connect. Make sure that resizing the spicy window will resize the
virtual Windows desktop (in spicy: Options/Resize guest to match window size).

Install MS Office / Powerpoint.

### Create your Powerpoint presentation

Avoid slide transitions and other animation effects that take longer
than three seconds to complete after hitting PageDown.  If your existing
presentation makes use of longer effects, you will have to adjust
the ```MUXSA_KVM2PNG_SLEEP``` parameter, see below.

### Create screenshots (PNG files) of your presentation

The ```muxsa-kvm2png``` script will take screenshots, save them into
numbered png files, and press PageDown, until the end of the presentation
is reached.

You might want to create a configuration file: 

    user@linux:~$ vi ~/.muxsarc
    MUXSA_KVM2PNG_VM_NAME="win10-office"
    MUXSA_KVM2PNG_EXTRA_Y="26"
    MUXSA_KVM2PNG_BUGFIX_SHOOT_TWICE="1"

The first line gives the name of the virtual machine we had created above.

Due to the menu bar in the spicy window, the window has to be resized to
a size slightly larger than the desired output video size. A value of
```MUXSA_KVM2PNG_EXTRA_Y="26"``` works for me, but with different 
window managers and font selections you might need a different value. 
If the value is wrong, the ```muxsa-kvm2png``` script will produce a warning.

I have observed that with some versions of libvirt, in some circumstances
the screenshot was garbled. Always taking two screenshots in a row and
using only the second one has worked for me. This can be enabled with
```MUXSA_KVM2PNG_BUGFIX_SHOOT_TWICE="1"```.

The script detects the end of the presentation by computing the MD5 digest
over each screenshot. If the script does not stop at the end of the 
presenation, but takes screenshots of that last "end of presentation screen"
slide again and again, you will have to compute the MD5 digest value
of that screenshot, e.g., with ```md5sum 0042.png``` and set
```MUXSA_KVM2PNG_MD5_LAST_SLIDE``` accordingly.

There are further configuration variables that can be set, either in
```$HOME/.muxsarc``` or by ```export MUXSA_KVM2PNG_BUGFIX_SHOOT_TWICE="1"```
on the command line; see the script for a full list.

If everything works as expected, the script will stop at the end of the
presentation and you will find files ```0000.png```, ```0001.png```, 
```0002.png```, ```0003.png```, ```...``` in your current directory.

### Create "presenter view" PNG files

Go to the directory with the screenshot PNG files from the previous
and start ```muxsa-pv```. 

It will create a subdirectory ```presenter-view``` and create a files with
the same name as in the parent directory, as a "presenter view" similar to
powerpoint, i.e. the current slide on the left, the next slide as a preview on
the right.

## Record background narration

### Hardware

*Note well:* For the sake of completeness, the author has decided to document
the audio hardware used in his home office recording studio. The author has
bought this hardware from his own personal money (a similar but different
set of hardware has been provided by his employer for use in the office).
The author did not receive any free products, compensation, or other
incentives from the vendors. The devices were chosen in the summer of 2020,
based on expected quality, perceived value-for-money, and availability,
when many products were not available or had very long lead times due to the
stalled supply chains. Lots of new products have been put on the market
since then. The author is not an expert in this field of technology. 
While the author is pleased with his setup, *this is NOT
a purchasing recommendation.* There are many excellent youtube channels 
that feature product reviews and comparisons, e.g., 
[Podcastage on youtube](https://www.youtube.com/c/Podcastage),
[TomBuck on youtube](https://www.youtube.com/c/TomBuck), and
[JulianKrause on youtube](https://www.youtube.com/c/JulianKrause).

The author uses this audio gear:

* Microphone: Rode Procaster
* Wind screen: Rode WS2
* Boom arm and shock mount: Rode PSA1 and Rode PSM1
* Microphone cable: XLR cable male to female, 3 meters
* XLR/USB audio interface: Motu M2
* Headphones: Beyerdynamic DT 770 Pro (32 Ohm)

Connect the microphone to the left XLR socket "IN 1L" of the Motu M2.
The Rode Procaster is a dynamic microphone that does not need phantom
power. If the red "48 V" button on the Motu M2 is illuminated, push
that button to turn phantom power off.

Recording took place in a rather small room with carpet floor and lots of
shelves and other furniture in it, i.e., no large flat surfaces except for
the ceiling. The author has performed some experiments, putting moving
blankets in front of walls and pillows on the desk in order to absorb some
sound reflections, but the audible difference was rather limited.

### Software drivers

Debian Linux 11 normally uses ```pulseaudio``` to route different audio streams
from microphones to applications and from applications to headsets or
speakers, respecively, as well as for mixing streams and resampling
different sample rates. While these functions are useful for desktop usage,
they add another layer of indirection, which can make our setup more
unpredictable.  Therefore, the author has decided to exclude the audio
interface from pulseaudio.

Find the vendor and device ID:

    user@linux:~$ lsusb  | grep -i unicorn
    Bus 001 Device 003: ID 07fd:0008 Mark of the Unicorn

Exclude it from pulseaudio:

    root@linux:~# cat > /etc/udev/rules.d/89-pulseaudio-usb.rules
    # MOTU M2 USB sound interface: do not show in pulse, direct alsa access
    ATTRS{idVendor}=="07fd", ATTRS{idProduct}=="0008", ENV{PULSE_IGNORE}="1"
    ^D
    root@linux:~# shutdown -r now

Install the JACK Audio Connection Kit sound server

    root@linux:~# apt-get install jackd jackd1

Start jackd

    user@linux:~$ jackd -r -dalsa -dhw:M2 -r48000 -p64 -n3

### Test recording

Now that jackd is running, start Audacity.

    user@linux:~$ audacity

In the pulldown menu below the "pause" button select "JACK Audio Connection
Kit". In the two pulldown menus right to the microphone symbol, select
"system" and "1 (Mono) Recording Channel", respectively. In the pulldown
menu right to the speaker symbol, select "system".

At the left bottom of the window, set the "Project Rate (Hz)" to 48000.

The next settings depend on your voice and your preferences, but you may
use these as a starting point for your own experiments.  At the Motu M2
interface set
* at the "IN 1L" side, where the microphone is plugged in
    * GAIN to about "3 o'clock" position
    * Phantom power off (the red "48V" LED does not light up)
    * Direct monitoring on (the blue "MON" LED is lit)
* at the "IN 2R" side, where no microphone is connected to
    * GAIN to minimum, i.e., about "7 o'clock" position
    * Phantom power off (the red "48V" LED does not light up)
    * Direct monitoring off (the blue "MON" LED does not light up)
* Monitor to minimum, i.e., big knob to about "7 o'clock" position
* Headphone volume (small knob at the very right) to about "3 o'clock" position

Adjust the boom arm such that the tip of the microphone points at a 45
degree angle to one corner of your mouth and that the microphone is very
close to your mouth, about 50 mm (2 inches) away from your face.

Avoid talking straight at a 0 degree angle into the microphone, as the wind
gusts caused when you speak so-called plosives (i.e., words with the letter
"p" etc.) may cause unpleasant sounds in the recording. Use your headphones
with the direct monitoring feature while you are speaking to identify such
unpleasant sounds.

In Audacity, hit the record button and speak some test sentences. 
Hit stop when you are done.  Hit the play button to listen to your
recording.  While listening to the recording and in particular while
editing the recording (see below), it is wise to turn off the direct
monitoring feature (blue button on the Motu M2), to make sure that
any sound picked up by the microphone (e.g., keyboard klicks) 
at that time is not mixed with the playback.

While you are recording or while you are listening to the playback, inspect
the volume meter. While you are speaking, the volume bars should go most of
the time up to -12 dB, sometimes up to -6 dB when you are exited and loud,
and never over -3 dB, even if you clap your hands or do other very loud
stuff.  Depending on your voice characteristics and the microphone you are
using, you might need to adjust the input GAIN knob accordingly.

### Record your audio

The core idea of muxsa, i.e, using Audacity's label track to control
the slide transitions, is presented in the [Demonstration video](https://nks-devel3.rus.uni-stuttgart.de/muxsa/making_of_netsec_2020.mp4).

### Enable Audacity's scripting module

As a preparation for the next step, in Audacity go to:
Edit / Preferences ... / Modules and set "mod-script-pipe" to "enabled".
Restart Audacity.  Now you should find two named pipes:

    /tmp/audacity_script_pipe.from.1000
    /tmp/audacity_script_pipe.to.1000

(1000 is the author's user ID, yours might be different, see id -u).

### More efficient recording with muxsa-vr

You can use a "wireless presenter", i.e., a small handheld transmitter,
usually with a laser pointer, that is often used for giving presentations.
```muxsa-vr``` receives the key strokes from that wireless presenter and sends
control commands simultaneously both to Audacity and geeqie, in order to
make recording, playback for review, deleting and re-recording, setting
labels with ascending slide numbers, switching to the next slide, etc. 
more convenient.

Start ```audacity``` as described above.

Start the ```geeqie``` image viewer in the directory with the
"presenter view" PNG files and go to the first slide.

Start a console/xterm window with a shell and start ```muxsa-vr``` there.
Keep the mouse/keyboard focus in that window. Press the "i" key on
the computer keyboard to initialize muxsa-vr. Then,

* pressing the "PageDown" key (usually the big right button) on the 
presenter starts recording a clip, if idle, or stops recording while in
recording state
* pressing the "PageUp" key (usually the big left button) plays the
most recently recorded clip 
* pressing the "F5/ESC" key (usually the small left button), deletes the 
most recently recorded clip - if you made an error and want to record it again. 
* pressing the "dot" key (usually the small right
button) moves on to the next slide.
* Further keys may be hit on the
computer's main keyboard to control muxsa-vr, press the "h" key for online
help. 

Depending on the specific hardware of your wireless presenter you might
need to make changes to muxsa-vr, which is a shell script.

### Audio post-processing

Improving audio quality with effects or filters is a science of its own and
it depends on your voice characteristics, the microphone you are using and
to some extent also personal taste.  Lots of good tutorials can be found on
youtube. The author uses these Audacity (version 2.4.2) effects in that
specific order; you can use that as a starting point for your own
experiments:

1. Noise Reduction

Record some seconds and try to be as silent as possible.  Mark this part of
the recording, click Effect / Noise Reduction / Step 1 / Get Noise Profile.
Then mark the whole track (Ctrl+A), and click Effect / Noise Reduction /
Step 2 / OK.

2. High-Pass filter

Mark the whole track (Ctrl+A), and click Effect / Plugin 1 to 15 / High Pass
Filter. Set "Frequency (Hz)" to "80" and "Roll-off (dB per octave)" to 
"6 dB", click OK. 

3. Compressor

Mark the whole track (Ctrl+A), and click Effect / Compressor. Set
* Threshold: -12 dB
* Noise Floor: -50 dB
* Ratio: 3:1
* Attack Time: 0.1 secs
* Release Time: 1.0 secs
* Check (enable) Make-up gain for 0 dB after compressing
* Check (enable) Compress based on Peaks

Click OK.  Then, click Effect / Amplify. Set "Amplification (dB)" to "-1.5"
and click OK. 

Reducing the peak amplitude leaves some headroom for further processing,
e.g., Equalizers (Effect / Graphic EQ), but the author normally does not use
an equalizer with his voice and this microphone.

### Further audio editing

If desired, listen to the whole recording again and cut out unwanted noise
or silence, see the demo video. As shown in the video, make sure to check
(enable) Tracks / Sync-Lock Tracks.

You can also mark noise and click "Generate/Silence" to mute that noise
without changing the length of the track. 

Heavy breathing should not be muted completely as this sounds strange, but
attenuated, maybe by 12 dB (Effect / Amplify / Amplification: -12 dB).  
If you need this attenuation by 12 dB often, assign a hot key:

    user@linux:~$ cat > $HOME/.audacity-data/Plug-Ins/attenuate12db.ny
    ;nyquist plug-in
    ;version 4
    ;type process
    ;name "Attenuate by -12 dB"
    ;action "Attenuate by -12 dB"
    ;author "Sebastian Kiesel"
    ;copyright "Released under terms of the GNU General Public License version 2"

    (mult *track* (db-to-linear -12.0))
    ^D

In Audacity: 
* Tools / Add|Remove Plug-Ins -> enable that plugin. 
* Edit / Preferences / Keyboard -> assign hotkey (e.g., PGDOWN)

There should be enough pauses before and after slide transitions.  As a rule
of thumb, use 3 seconds of silence before and after a slide transition.
This sounds like eternity while you are working with Audacity but is usually
not too long when the video is assembled.

### Export audio and label track.

As shown in the demo video, export the audio as ```soundtrack.m4a``` in the
m4a file format and the label track as ```LabelTrack.txt```. 
Save the Audacity project as ```NarrationForXYZPresentation.aup``` 
for further editing.

## Assemble the video

Convert the Audacity Label Track you have saved before to an ffmpeg
concat multiplexer control file by using:

    user@linux:~$ muxsa-al2fc LabelTrack.txt > slides.concat

Assume that the PNG files created above, the ```soundtrack.m4a```
and the ```slides.concat``` file are all in the current directory,
use 

    user@linux:~$ muxsa-pngaac2mp4

to assemble the final video named ```out.mp4```.  A different output
filename can be given as parameter to ```muxsa-pngaac2mp4```.

## Watch the video

You may use any video player to watch the mp4 video, e.g., on Linux use
```vlc``` or ```mplayer```.