# 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 step 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 from the side 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 and learn how to avoid them. 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-lit "MON" 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 Assuming 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```.