edu/muxsa
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add muxsa step-by-step howto

Browse Source
This commit is contained in:
Sebastian Kiesel 2023-07-30 18:46:15 +02:00
parent 0a19796698
commit cf071dd5c2
2 changed files with 366 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

@ -5,4 +5,5 @@ muxsa (MUltipleXer for Slides and Audio): a collection of Linux tools for effici
## Documentation ## 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) * [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) * [muxsa block diagram](doc/muxsa-blockdiagram.png)
* [Step-by-step HOWTO](doc/howto.md)
* [Dependencies](doc/dependencies.md) * [Dependencies](doc/dependencies.md)

365
doc/howto.md Normal file
View File

@ -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```.