From e7272b56def7f4c22eead4b80bd79cd32999a6bb Mon Sep 17 00:00:00 2001 From: Sebastian Kiesel Date: Sat, 15 Feb 2025 16:44:46 +0100 Subject: [PATCH] add man pages and Makefile to build them --- Makefile | 25 ++++++ man/man1/muxsa-al2fc.1.md | 66 ++++++++++++++ man/man1/muxsa-kvm2png.1.md | 160 +++++++++++++++++++++++++++++++++ man/man1/muxsa-pngaac2mp4.1.md | 76 ++++++++++++++++ man/man1/muxsa-pv.1.md | 40 +++++++++ man/man1/muxsa-rl.1.md | 40 +++++++++ man/man1/muxsa-vr.1.md | 40 +++++++++ 7 files changed, 447 insertions(+) create mode 100644 Makefile create mode 100644 man/man1/muxsa-al2fc.1.md create mode 100644 man/man1/muxsa-kvm2png.1.md create mode 100644 man/man1/muxsa-pngaac2mp4.1.md create mode 100644 man/man1/muxsa-pv.1.md create mode 100644 man/man1/muxsa-rl.1.md create mode 100644 man/man1/muxsa-vr.1.md diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..0655e04 --- /dev/null +++ b/Makefile @@ -0,0 +1,25 @@ +.PHONY: all clean install + +GENDOCS := doc/howto.html doc/howto.txt +MANPGS := man/man1/muxsa-kvm2png.1.gz \ + man/man1/muxsa-al2fc.1.gz \ + man/man1/muxsa-pngaac2mp4.1.gz \ + man/man1/muxsa-pv.1.gz \ + man/man1/muxsa-rl.1.gz \ + man/man1/muxsa-vr.1.gz + +all: $(GENDOCS) $(MANPGS) + +clean: + rm -f $(GENDOCS) $(MANPGS) + +%.html : %.md + pandoc -f markdown -t html $^ > $@ + +%.txt : %.md + pandoc -f markdown -t plain $^ > $@ + +%.1.gz : %.1.md + pandoc --standalone -f markdown -t man $^ | gzip -9 > $@ + +install: diff --git a/man/man1/muxsa-al2fc.1.md b/man/man1/muxsa-al2fc.1.md new file mode 100644 index 0000000..1c94e33 --- /dev/null +++ b/man/man1/muxsa-al2fc.1.md @@ -0,0 +1,66 @@ +% muxsa-al2fc(1) Version 1.0 |MUltipleXer for Slides and Audio + +NAME +==== + +**muxsa-al2fc** — convert Audacity label track to ffmpeg concat multiplexer control file. + +SYNOPSIS +======== + +| **muxsa-al2fc** _LabelTrack.txt_ > _slides.concat_ + + +DESCRIPTION +=========== + +**muxsa-al2fc** is part of muxsa (MUltipleXer for Slides and Audio), +a collection of Linux tools for efficiently creating video files from +presentation slides and background narration. +For an overview on muxsa, see +[/usr/share/doc/muxsa/howto.txt](/usr/share/doc/muxsa/howto.txt) and +[https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa](https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa). + +**muxsa-al2fc** reads a label track exported from the **audacity**(1) audio +editor and writes (to stdout) a control file, typically to be used with +**muxsa-pngaac2mp4**(1), which basically calls the **ffmpeg**(1) concat +multiplexer. + +Options +------- + +(none) + +FILES +===== + +*~/.muxsarc* + +: Per-user default configuration file. Can be + used to define the environment variables listed below. + +ENVIRONMENT +=========== + +**MUXSA_al2fc_SLIDE_PREFIX** + +: The screenshots that were created with **muxsa-kvm2png**(1) are + are assumed to be in files named with this prefix, followed by + a four-digit number and *.png*. + Default value: "" (empty), i.e., screenshots are + *0000.png*, *0001.png*, *0002.png*, ... in the current directory. + +BUGS +==== + +See: + +AUTHOR +====== + +Sebastian Kiesel + +SEE ALSO +======== + +**muxsa-kvm2png(1)**, **muxsa-pngaac2mp4(1)** diff --git a/man/man1/muxsa-kvm2png.1.md b/man/man1/muxsa-kvm2png.1.md new file mode 100644 index 0000000..b515337 --- /dev/null +++ b/man/man1/muxsa-kvm2png.1.md @@ -0,0 +1,160 @@ +% muxsa-kvm2png(1) Version 1.0 | MUltipleXer for Slides and Audio + +NAME +==== + +**muxsa-kvm2png** — takes a series of screenshots from a virtual machine + +SYNOPSIS +======== + +| **muxsa-kvm2png** + +DESCRIPTION +=========== + +**muxsa-kvm2png** is part of muxsa (MUltipleXer for Slides and Audio), +a collection of Linux tools for efficiently creating video files from +presentation slides and background narration. +For an overview on muxsa, see +[/usr/share/doc/muxsa/howto.txt](/usr/share/doc/muxsa/howto.txt) and +[https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa](https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa). + +**muxsa-kvm2png** assumes that a virtual machine under Linux/KVM with +**spicy**(1) display is running, typically with some slide presentation +software, such as Powerpoint in Windows or Libreoffice in Windows or Linux, +running on it. It will repeatedly take screnshots and press the PageDown key, +until some kind of "end of presentation" screen is detected. + +Options +------- + +(none) + +FILES +===== + +*~/.muxsarc* + +: Per-user default configuration file. Will be sourced by bash and can be + used to define the environment variables listed below. + +*0000.png*, *0001.png*, *0002.png*, ... + +: Default file names of the screenshots taken. + See environment variable **MUXSA_KVM2PNG_SLIDE_PREFIX** below. + + +ENVIRONMENT +=========== + +**MUXSA_KVM2PNG_VM_NAME** + +: The name of the virual machine, as can be shown with + **virsh -c qemu:///system list**. + Default value: _win10-office_ + + +**MUXSA_KVM2PNG_SIZE_X** + +: Desired width of the screenshots to be taken, in pixels. + **muxsa-kvm2png** will invoke **xdotool**(1) to resize the + **spicy**(1) window, if needed. + Default value: _1920_ + + +**MUXSA_KVM2PNG_SIZE_Y** + +: Desired height of the screenshots to be taken, in pixels. + Default value: _1080_ + + +**MUXSA_KVM2PNG_EXTRA_X** + +: Extra window width, to account for menus and window decoration. + If needed, **muxsa-kvm2png** will invoke **xdotool**(1) to resize the + **spicy**(1) window to a witdh + of **MUXSA_KVM2PNG_SIZE_X** + **MUXSA_KVM2PNG_EXTRA_X**. + Default value: _0_ + + +**MUXSA_KVM2PNG_EXTRA_Y** + +: Extra window height, to account for menus and window decoration. + If needed, **muxsa-kvm2png** will invoke **xdotool**(1) to resize the + **spicy**(1) window to a height + of **MUXSA_KVM2PNG_SIZE_Y** + **MUXSA_KVM2PNG_EXTRA_Y**. + Default value: _0_ ; in many cases a value of _28_ is useful. + + +**MUXSA_KVM2PNG_SLIDE_PREFIX** + +: The screenshots will be saved in files named with this prefix, followed by + a four-digit number and *.png*. + Default value: "" (empty), i.e., screenshots will be saved as + *0000.png*, *0001.png*, *0002.png*, ... in the current directory. + + +**MUXSA_KVM2PNG_SLIDE_NUMBER_START** + +: First number to be used as the four digit sequence number for + the screenshot file names. + Default value: _0_ (will be padded to four digits automatically). + + +**MUXSA_KVM2PNG_SLIDE_NUMBER_END** + +: Last number to be used as the four digit sequence number for + the screenshot file names. + Default value: _9999_ + + +**MUXSA_KVM2PNG_FORCE_OVERWRITE** + +: If set to _1_, existing screenshot files will be overwritten + without asking the user for confirmation. Otherwise, the program + will abort if a file already exists. + Default value: "" (empty) + + +**MUXSA_KVM2PNG_BUGFIX_SHOOT_TWICE** + +: There have been bug reports, that with some versions of + KVM/libvirt/spicy, the screenshots were sometimes garbled. + As a workaround, if this variable is set to _1_, always take + two screenshots in a row, discard of the first one, and only + use the second one, which always seemed to be intact in these scenarios. + Default value: "" (empty) + + +**MUXSA_KVM2PNG_SLEEP** + +: Sleep time in seconds to wait after emulating a PageDown keystroke, + before taking the next screenshot. Adjust to a longer interval + if your slide presentation uses slide transition effects that take + longer to settle. + Default value: _3_ (seconds). + + +**MUXSA_KVM2PNG_MD5_LAST_SLIDE** + +: Stop taking screenshots after a .png file with this **md5sum**(1) + output has been shot. + Default value: _092eb68a91b4d2a73833f00a01dc5cb0_ + ("End of slide show. click to exit." screen of Powerpoint, + screenshot taken at 1920x1080 pixels). + +BUGS +==== + +See: + +AUTHOR +====== + +Sebastian Kiesel + +SEE ALSO +======== + +**muxsa-al2fc(1)**, **muxsa-pngaac2mp4(1)** diff --git a/man/man1/muxsa-pngaac2mp4.1.md b/man/man1/muxsa-pngaac2mp4.1.md new file mode 100644 index 0000000..235ea12 --- /dev/null +++ b/man/man1/muxsa-pngaac2mp4.1.md @@ -0,0 +1,76 @@ +% muxsa-pngaac2mp4(1) Version 1.0 | MUltipleXer for Slides and Audio + +NAME +==== + +**muxsa-pngaac2mp4** — multiplex slides and background narration into a video file + +SYNOPSIS +======== + +| **muxsa-pngaac2mp4** \[**-a** _soundtrack.m4a_] \[**-s** _slides.concat_] \[**-o** _out.mp4_] + +DESCRIPTION +=========== + +**muxsa-pngaac2mp4** is part of muxsa (MUltipleXer for Slides and Audio), +a collection of Linux tools for efficiently creating video files from +presentation slides and background narration. +For an overview on muxsa, see +[/usr/share/doc/muxsa/howto.txt](/usr/share/doc/muxsa/howto.txt) and +[https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa](https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa). + +**muxsa-pngaac2mp4** calls **ffmpeg**(1) with its concat multiplexer. +It reads a series of images in _.png_ file format, typically screenshots +of a slide presentation that were taken with **muxsa-kvm2png**(1), +an audio file in _.m4a_ file format with the narration, typically +recorded with **audacity**(1), and a control file containing the +image file names and timing information, typically generated with +**muxsa-al2fc**(1) from an **audacity**(1) label track. +It produces a video file in _.mp4_ file format. + +Options +------- + +-a _alternate-soundtrack.m4a_ + +: Name of aac/m4a audio file with the background narration. + Default: _soundtrack.m4a_ + +-s _alternate-control-file.concat_ + +: Name of the ffmpeg concat multiplexer control file, typically + generated with **muxsa-al2fc**(1). + Default: _slides.concat_ + +-o _alternate-output.mp4_ + +: Name of the video file in _.mp4_ format to be written. + Default: _out.mp4_ + +FILES +===== + +*soundtrack.m4a*, *slides.concat*, *out.mp4* + +: Default file names. Description: see Options section. + +ENVIRONMENT +=========== + +(none) + +BUGS +==== + +See: + +AUTHOR +====== + +Sebastian Kiesel + +SEE ALSO +======== + +**muxsa-al2fc(1)**, **muxsa-kvm2png(1)** diff --git a/man/man1/muxsa-pv.1.md b/man/man1/muxsa-pv.1.md new file mode 100644 index 0000000..ac5916d --- /dev/null +++ b/man/man1/muxsa-pv.1.md @@ -0,0 +1,40 @@ +% muxsa-pv(1) Version 1.0 | MUltipleXer for Slides and Audio + +NAME +==== + +**muxsa-pv** — generate "presenter view" images from presentation slides + +SYNOPSIS +======== + +| **muxsa-pv** + +DESCRIPTION +=========== + +**muxsa-pv** is part of muxsa (MUltipleXer for Slides and Audio), +a collection of Linux tools for efficiently creating video files from +presentation slides and background narration. +For an overview on muxsa, see +[/usr/share/doc/muxsa/howto.txt](/usr/share/doc/muxsa/howto.txt) and +[https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa](https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa). + +There is no extensive documentation for this utility program at this +point in time. Please refer to the howto documentation (see above) +and the source code of this script. + +BUGS +==== + +See: + +AUTHOR +====== + +Sebastian Kiesel + +SEE ALSO +======== + +**muxsa-al2fc(1)**, **muxsa-kvm2png(1)**, **muxsa-pngaac2mp4(1)** diff --git a/man/man1/muxsa-rl.1.md b/man/man1/muxsa-rl.1.md new file mode 100644 index 0000000..6ec0215 --- /dev/null +++ b/man/man1/muxsa-rl.1.md @@ -0,0 +1,40 @@ +% muxsa-rl(1) Version 1.0 | MUltipleXer for Slides and Audio + +NAME +==== + +**muxsa-rl** — renumber labels in **audacity**(1) via scripting interface + +SYNOPSIS +======== + +| **muxsa-rl** _labeltext_,_labeltext_,... + +DESCRIPTION +=========== + +**muxsa-rl** is part of muxsa (MUltipleXer for Slides and Audio), +a collection of Linux tools for efficiently creating video files from +presentation slides and background narration. +For an overview on muxsa, see +[/usr/share/doc/muxsa/howto.txt](/usr/share/doc/muxsa/howto.txt) and +[https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa](https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa). + +There is no extensive documentation for this utility program at this +point in time. Please refer to the howto documentation (see above) +and the source code of this script. + +BUGS +==== + +See: + +AUTHOR +====== + +Sebastian Kiesel + +SEE ALSO +======== + +**muxsa-al2fc(1)**, **muxsa-kvm2png(1)**, **muxsa-pngaac2mp4(1)** diff --git a/man/man1/muxsa-vr.1.md b/man/man1/muxsa-vr.1.md new file mode 100644 index 0000000..62b3d44 --- /dev/null +++ b/man/man1/muxsa-vr.1.md @@ -0,0 +1,40 @@ +% muxsa-vr(1) Version 1.0 | MUltipleXer for Slides and Audio + +NAME +==== + +**muxsa-vr** — Remote control for **audacity**(1) as a voice recorder + +SYNOPSIS +======== + +| **muxsa-vr** + +DESCRIPTION +=========== + +**muxsa-vr** is part of muxsa (MUltipleXer for Slides and Audio), +a collection of Linux tools for efficiently creating video files from +presentation slides and background narration. +For an overview on muxsa, see +[/usr/share/doc/muxsa/howto.txt](/usr/share/doc/muxsa/howto.txt) and +[https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa](https://git-nks-public.tik.uni-stuttgart.de/edu/muxsa). + +There is no extensive documentation for this utility program at this +point in time. Please refer to the howto documentation (see above) +and the source code of this script. + +BUGS +==== + +See: + +AUTHOR +====== + +Sebastian Kiesel + +SEE ALSO +======== + +**muxsa-al2fc(1)**, **muxsa-kvm2png(1)**, **muxsa-pngaac2mp4(1)**