From cf071dd5c2865a9df95b5945936358d636ad3ef8 Mon Sep 17 00:00:00 2001 From: Sebastian Kiesel Date: Sun, 30 Jul 2023 18:46:15 +0200 Subject: [PATCH] Add muxsa step-by-step howto --- README.md | 1 + doc/howto.md | 365 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 366 insertions(+) create mode 100644 doc/howto.md diff --git a/README.md b/README.md index f85ad2d..a7b75d4 100644 --- a/README.md +++ b/README.md @@ -5,4 +5,5 @@ muxsa (MUltipleXer for Slides and Audio): a collection of Linux tools for effici ## Documentation * [Demonstration video (a.k.a. the making of Network Security 2020)](https://nks-devel3.rus.uni-stuttgart.de/muxsa/making_of_netsec_2020.mp4) * [muxsa block diagram](doc/muxsa-blockdiagram.png) +* [Step-by-step HOWTO](doc/howto.md) * [Dependencies](doc/dependencies.md) diff --git a/doc/howto.md b/doc/howto.md new file mode 100644 index 0000000..19cd343 --- /dev/null +++ b/doc/howto.md @@ -0,0 +1,365 @@ +# 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](doc/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: ```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 file on the left, the next file 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" + * 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" + * 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" + +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) 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 my 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. + +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```.