Added sonivoxrender program man page

Closes #24

CMakeLists.txt

@@ -18,13 +18,14 @@ cmake_minimum_required(VERSION 3.14)
 
 project( sonivox
     LANGUAGES C CXX
-    VERSION 3.6.13.0
+    VERSION 3.6.14.0
 )
 
 # GoogleTest requires at least C++14
 set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD_REQUIRED TRUE)
 
-option(USE_44KHZ "Output 44100 Hz audio (instead of 22050 Hz)" TRUE)
+option(USE_44KHZ "Output 44100 Hz audio sample rate (instead of 22050 Hz)" TRUE)
 option(USE_16BITS_SAMPLES "Use 16 bits samples (instead of 8 bit)" TRUE)
 option(BUILD_SONIVOX_STATIC "Build the static library" TRUE)
 option(BUILD_SONIVOX_SHARED "Build the shared library" TRUE)
@@ -33,8 +34,13 @@ option(BUILD_TESTING "Build the unit tests" TRUE)
 option(CMAKE_POSITION_INDEPENDENT_CODE "Whether to create position-independent targets" TRUE)
 set(MAX_VOICES 64 CACHE STRING "Maximum number of voices")
 
+include(CMakeDependentOption)
+cmake_dependent_option(BUILD_MANPAGE "Build the manpage of the example program" FALSE "BUILD_EXAMPLE" FALSE)
+
 include(GNUInstallDirs)
 
+set(PROJECT_RELEASE_DATE "October 6, 2024")
+
 if (BUILD_TESTING)
     find_package(GTest CONFIG)
     if (NOT GTest_FOUND)

example/CMakeLists.txt

@@ -21,3 +21,39 @@ if (BUILD_SONIVOX_STATIC)
 elseif (BUILD_SONIVOX_SHARED)
     target_link_libraries ( sonivoxrender sonivox::sonivox )
 endif()
+
+if (BUILD_MANPAGE)
+    if(NOT EXISTS ${PANDOC_EXECUTABLE})
+        find_program(PANDOC_EXECUTABLE pandoc)
+        mark_as_advanced(PANDOC_EXECUTABLE)
+    endif()
+
+    if (EXISTS ${PANDOC_EXECUTABLE})
+        set(_src ${CMAKE_CURRENT_SOURCE_DIR}/sonivoxrender.1.md)
+        if (NOT PROJECT_RELEASE_DATE)
+            unset(_date)
+            execute_process (
+                COMMAND bash -c "LANG=en;date +'%B %d, %Y'"
+                OUTPUT_VARIABLE _date
+                OUTPUT_STRIP_TRAILING_WHITESPACE
+            )
+        else()
+            set(_date ${PROJECT_RELEASE_DATE})
+        endif()
+        set(_footer "${PROJECT_NAME} ${PROJECT_VERSION}")
+        add_custom_command (
+            OUTPUT sonivoxrender.1
+            COMMAND ${PANDOC_EXECUTABLE} -s -t man -Vdate=${_date} -Vfooter=${_footer} ${_src} -o sonivoxrender.1
+            DEPENDS ${_src}
+            WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+            VERBATIM
+        )
+        add_custom_target(manpage ALL DEPENDS sonivoxrender.1)
+    endif()
+else()
+    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/sonivoxrender.1 ${CMAKE_CURRENT_BINARY_DIR} COPYONLY)
+endif()
+
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/sonivoxrender.1
+    DESTINATION ${CMAKE_INSTALL_MANDIR}/man1
+)

example/sonivoxrender.1

@@ -0,0 +1,105 @@
+.\" Automatically generated by Pandoc 2.14.0.3
+.\"
+.TH "SONIVOXRENDER" "1" "October 6, 2024" "sonivox 3.6.14.0" "Sonivox MIDI File Renderer"
+.hy
+.SH NAME
+.PP
+\f[B]sonivoxrender\f[R] \[em] Render standard MIDI files into raw PCM
+audio
+.SH SYNOPSIS
+.PP
+\f[B]sonivoxrender\f[R] [\f[B]-h\f[R]] [\f[B]-d\f[R] \f[I]file.dls\f[R]]
+[\f[B]-r\f[R] \f[I]0..4\f[R]] [\f[B]-w\f[R] \f[I]0..32765\f[R]]
+\f[I]midi_file\f[R]
+.SH DESCRIPTION
+.PP
+This program is a MIDI file renderer based on the sonivox synthesizer
+library.
+It reads .MID (Standard MIDI Files) file format, and writes an audio
+stream to the standard output as raw 16 bit stereo PCM samples.
+.SS Options
+.TP
+-h
+Prints brief usage information.
+.TP
+-d \f[I]file.dls\f[R]
+Optional DLS soundfont file name.
+If not provided, it uses an internal embedded soundfont.
+.TP
+-r \f[I]reverb_preset\f[R]
+Reverb preset between 0 and 4: 0=no, 1=large hall, 2=hall, 3=chamber,
+4=room.
+.TP
+-w \f[I]reverb_wet\f[R]
+Reverb wet level between 0 and 32765.
+.SS Arguments
+.TP
+\f[I]midi_file\f[R]
+Input MID file name.
+.SH EXAMPLES
+.PP
+The following examples assume the default option USE_44KHZ=ON, which
+means an output sample rate = 44100 Hz.
+.PP
+Example 1: Render a MIDI file and save the rendered audio as a raw audio
+file:
+.IP
+.nf
+\f[C]
+$ sonivoxrender ants.mid > ants.pcm
+\f[R]
+.fi
+.PP
+Example 2: pipe the rendered audio thru the Linux ALSA \f[B]aplay\f[R]
+utility:
+.IP
+.nf
+\f[C]
+$ sonivoxrender ants.mid | aplay -c 2 -f S16_LE -r 44100
+\f[R]
+.fi
+.PP
+is equivalent to:
+.IP
+.nf
+\f[C]
+$ sonivoxrender ants.mid | aplay -f cd
+\f[R]
+.fi
+.PP
+Example 3: pipe the rendered audio thru the \f[B]lame\f[R] utility
+creating a MP3 file:
+.IP
+.nf
+\f[C]
+$ sonivoxrender ants.mid | lame -r -s 44100 - ants.mp3
+\f[R]
+.fi
+.PP
+Example 4: pipe the rendered audio thru the \f[B]sox\f[R] utility
+creating a WAV file:
+.IP
+.nf
+\f[C]
+$ sonivoxrender ants.mid | sox -t s16 -c 2 -r 44100 - ants.wav
+\f[R]
+.fi
+.PP
+Example 5: pipe the rendered audio thru the PulseAudio\[cq]s
+\f[B]pacat\f[R] utility:
+.IP
+.nf
+\f[C]
+$ sonivoxrender ants.mid | pacat
+\f[R]
+.fi
+.SH BUGS
+.PP
+See Tickets at GitHub <https://github.com/pedrolcl/sonivox/issues/>
+.SH LICENSE AND COPYRIGHT
+.PP
+Licensed under the Apache License, Version 2.0
+.PP
+Copyright (c) 2022-2024 Pedro L\['o]pez-Cabanillas and contributors
+.SH AUTHORS
+Pedro L\['o]pez-Cabanillas <[email protected]>.

example/sonivoxrender.1.md

@@ -0,0 +1,77 @@
+% SONIVOXRENDER(1) sonivoxrender 0.0.0 | Sonivox MIDI File Renderer
+% Pedro López-Cabanillas <[email protected]>
+
+# NAME
+
+**sonivoxrender** — Render standard MIDI files into raw PCM audio
+
+# SYNOPSIS
+
+| **sonivoxrender** [**-h**] [**-d** _file.dls_] [**-r** _0..4_] [**-w** _0..32765_] _midi_file_
+
+# DESCRIPTION
+
+This program is a MIDI file renderer based on the sonivox synthesizer library.
+It reads .MID (Standard MIDI Files) file format, and writes an audio stream to the standard output as raw 16 bit stereo PCM samples.
+
+## Options
+
+-h
+
+:   Prints brief usage information.
+
+-d  _file.dls_
+
+:   Optional DLS soundfont file name. If not provided, it uses an internal embedded soundfont.
+
+-r  _reverb_preset_
+
+:   Reverb preset between 0 and 4: 0=no, 1=large hall, 2=hall, 3=chamber, 4=room.
+
+-w  _reverb_wet_
+
+:   Reverb wet level between 0 and 32765.
+
+## Arguments
+
+_midi_file_
+
+:   Input MID file name.
+
+# EXAMPLES
+
+The following examples assume the default option USE_44KHZ=ON, which means an output sample rate = 44100 Hz.
+
+Example 1: Render a MIDI file and save the rendered audio as a raw audio file:
+
+    $ sonivoxrender ants.mid > ants.pcm
+
+Example 2: pipe the rendered audio thru the Linux ALSA **aplay** utility:
+
+    $ sonivoxrender ants.mid | aplay -c 2 -f S16_LE -r 44100
+
+is equivalent to:
+
+    $ sonivoxrender ants.mid | aplay -f cd
+
+Example 3: pipe the rendered audio thru the **lame** utility creating a MP3 file:
+
+    $ sonivoxrender ants.mid | lame -r -s 44100 - ants.mp3
+
+Example 4: pipe the rendered audio thru the **sox** utility creating a WAV file:
+
+    $ sonivoxrender ants.mid | sox -t s16 -c 2 -r 44100 - ants.wav
+
+Example 5: pipe the rendered audio thru the PulseAudio's **pacat** utility:
+
+    $ sonivoxrender ants.mid | pacat
+
+# BUGS
+
+See Tickets at GitHub <https://github.com/pedrolcl/sonivox/issues/>
+
+# LICENSE AND COPYRIGHT
+
+Licensed under the Apache License, Version 2.0
+
+Copyright (c) 2022-2024 Pedro López-Cabanillas and contributors