
jack_capture V0.9.34
Released 2009-05-19
Kjetil S. Matheussen



ABOUT
*****
jack_capture is a program for recording soundfiles with jack. Its default
operation is to capture whatever sound is going out to your speakers into
a file.

This is the program I always wanted to have for jack, but no
one made. So here it is.


COMMON USAGE
************
$jack_capture



ADVANCED USAGE
**************
jack_capture  [--bitdepth n] [--bufsize seconds] [--channels n] [--port port] [filename]
              [ -b        n] [ -B       seconds] [ -c        n] [ -p    port]

"filename" is by default auotogenerated to something like "jack_capture_<number>.wav"
"bitdepth" is by default FLOAT. It can be set to either 8, 16, 24 or 32.
"channels" is by default 2.
"bufsize"  is by default 20 seconds.
"port"     is by default set to the physical outputs, which means that jack_capture
           will be constantly connected to the ports connecting to the
           physical outputs. The "port" argument can be specified more than once.


Additional arguments:
[--duration s] or [-d s]         -> Recording is stopped after "s" seconds.
[--leading-zeros n] or [-z n]    -> "n" is the number of zeros to in the autogenerated filename.
                                    (-z 2 -> jack_capture_001.wav, and so on.) (default is 1)
[--format format] or [-f format] -> See http://www.mega-nerd.com/libsndfile/api.html#open
                                    (Default is wav)
[--print-formats] or [-pf]       -> Prints all valid sound formats to screen and then exits.
[--version] or [-v]              -> Prints out version.
[--silent] or [-s]               -> Suppress some common messages printed to the terminal.
[--verbose] or [-V]              -> Prints some extra information to the terminal.
[--write-to-stdout] or [-ws]     -> Write 16 bit little endian to stdout.
[--disable-meter] or [-dm]       -> Disable console meter
[--hide-buffer-usage] or [-hbu]  -> Disable buffer usage.
[--disable-console] or [-dc]     -> Disable console updates. Same as "-dm -hbu".
[--dB-meter] or [-dB]            -> Use dB scale for the console meter
[--dB-meter-reference or [-dBr]  -> Specify reference level for dB meter. (default=0)
[--meterbridge] or [-mb]         -> Start up meterbridge to monitor recorded sound.
[--meterbridge-type] or [-mt]    -> Specify type. vu (default), ppm, dpm, jf or sco.
[--meterbridge-reference]/[-mr]  -> Specify reference level for meterbidge.
[--maxbufsize] or [-MB]          -> Maximum buffer size jack_capture will allocate
[--filename] or [-fn]            -> Specify filename.
                                    (It's usually easier to set last argument instead)

Examples:

To record a stereo file of what you hear:
  $jack_capture

To record a stereo file of what you hear in the flac format:
 $jack_capture -f flac

To record a stereo file of what you hear in the mp3 format:
 $jack_capture -ws|lame -V2 -r -x - output.mp3

To record a stereo file of what you hear in the ogg format:
 $jack_capture -ws|oggenc -o output.ogg -r -

To record a stereo file of what you hear (same as the default):
  $jack_capture --port system:playback_1 --port system:playback_2

Same result as above, but using a different syntax:
  $jack_capture --channels 2 --port system:playback*

To record the output from jamin:
  $jack_capture --port jamin:out* sound_from_jamin.wav

To record all sound coming in to jamin:
  $jack_capture --port jamin:in* sound_to_jamin.wav

To record all sound coming in and out of jamin:
  $jack_capture --port jamin* sound_to_and_from_jamin.wav

To record a stereo file from the soundcard:
  $jack_capture -c 2 -p system:capture*



ACKNOWLEDGMENT
**************
Originally based on the jackrec program in the jack distribution
made by Paul Davies and Jack O'Quin. Not much left of that code now.
http://www.jackaudio.org

Peak indicator code for the console meter taken
from meterbridge by Steve Harris.
http://plugin.org.uk/meterbridge/

Unmodified atomic lifo/fifo code taken from midishare. (Copyright Grame 1999-2005)
http://midishare.sf.net

Code for writing to stdout was made by looking at http://mir.dnsalias.com/oss/jackstdout/start
made by Robin Gareus.



CHANGES
*******
0.9.33 -> 0.9.34:
 * Added untested patch from Orcan Ogetbil to make jack_capture compile on a ppc64 platform.
   In case jack_capture is ran on a ppc64 platform, a warning is printed during runtime.


0.9.32 -> 0.9.33:
 *Clearing up licenses
 *A fix for open() from Florian Faber.
 *A couple of gui fixes from Orcan Ogetbil.


0.9.31 -> 0.9.32:
 *Changed default format for from wav to wavex for files with more
  than two channels. Thanks to Fons Adriaensen for the suggestion.
 *Added fix for 64 bit mode. Thanks to Andras Simon for helping
  to find the bug and Dominique Fober for fixing the bug.
 *Added the "-verbose" option for easier debugging in case program
  crashes or freezes.
 *Checks if sndfile.h exist before generating setformat.c.


0.9.30 -> 0.9.31:
 *Cleaned up exit handling and connection thread startup.
  When recording is stopped, the "Please wait, writing to disk"
  message is visible, and the console is not removed until
  everything is written to disk.


0.9.29 -> 0.9.30:
 *Added Hermann Meyer's jack_capture_gui2 program.
  jack_capture_gui2 is a nice graphical frontend
  for for jack_capture with lots of options.
  Many thanks to Herman for the contribution.


0.9.28 -> 0.9.29:
 *Don't exit in case port is not found.
 *Print runtime warning and error messages on top of the
  console to avoid printing the console meter yet another time.
  (it's much prettier also)


0.9.27 -> 0.9.28:
 *Fixed a bug that could cause (and especially after the switch
  from calloc to my_calloc apparantely) segfault when specifying
  --port more than once. Thanks to Peder Hedlund for spotting
  the bug.
 *Print error instead of segfaulting when a specified jack port
  does not exist.
 *Removed -g option and changed -O0 to -O2. (Oops, don't know
  how long that's been there)


0.9.26 -> 0.9.27:
 *Make sure the stop semaphore is initialized before it might
  be called.


0.9.25-beta -> 0.9.26:
 *Changed the --recording-time / -d option to record exactly the
  correct number of frames. (The format for the option is still
  in seconds though). This fixes the problem where the wall
  clock and the soundcard clock drifts apart.
 *Always increase the buffer size with 2 seconds when more than
  than half the buffer is used, unless maximum buffer size is reached.
 *Added the --maxbufsize / -MB option which sets maximum buffer size.
  Default value is 40 seconds.
 *Decreased the default buffer size from 20 to 10 seconds.


0.9.24-beta -> 0.9.25-beta:
 *Do not use this release!
 *Cleaned up lots of stuff and added support for blocksize change
  again.
 *Lots of internal changes:
  Don't use this release for important recordings!


0.9.23 -> 0.9.24-beta:
 *Do not use this release!
 *Changed internal data representation from lockless ringbuffer to
  lockless lifo and fifo stacks. Unmodified lifo/fifo code taken
  from midishare. (Copyright Grame 1999-2005)
 *The code is much prettier now because of the lifo/fifo thing,
  but I haven't looked too much at it yet, so this version
  might very well contain serious bugs which could destroy
  your recording.


0.9.22 -> 0.9.23:
 *Minor spellings
 *Check for out of memory


0.9.22 -> 0.9.22:
 *Clean up source a bit
 *Stop connection thread before closing jack client.
 *Made --help a tiny bit cleaner


0.9.20 -> 0.9.21:
 *Removed shut down code from the SIGINT signal handler.


0.9.19 -> 0.9.20:
 *Fixed segfault in case jack shuts down. Thanks to Julien Claassen
  for reporting the bug.


0.9.18 -> 0.9.19:
 *Do not accept filename starting with "-" when filename is last argument.
 *Added the "--filename"/"-fn" option to set filename not
  as the last argument. Can also contain "-" as first character.
 *Fixed colors a bit and removed a superfluous linebreak.
 *Fixed segfault for missing values in commandline.
 *Manually clear allocated memory instead of using calloc.
 *Removed buffer-info line when recording to stdout.


0.9.17 -> 0.9.18:
 *Removed printing of "continue recording" when writing the last overruns.
 *Niceify the disk writing thread to -20 when more than half the buffer is used.
 *Continously show buffer usage, total number of overruns and whether
  the disk thread has high priority, in the console. Turn off by using 
  the -hdu option.
 *Added option -dc to disable console update. (same as "-dm -hdu")
 *Fancier colors.
 *Removed "hepp".
 *Made dB meter the default and replaced the -dB option with the -lm option.
 *Made the console meter wider to fit the info line at the bottom.


0.9.16 -> 0.9.17:
 *Made sure the process thread won't continue sending
  data when jack_capture is told to quit. This
  lead to race conditions when recording too many channels
  (256 channels on my machine).
 *Added the jack_capture_gui script, based on code
  by Svend-Erik Kjær Madsen's.


0.9.15 -> 0.9.16:
 *Replaced sh by bash to make it work in ubuntu.


0.9.14 -> 0.9.15:
 *Fixed exact port name match and gen_setformat. Thanks to
  Gabriel J.L. Beckers for reporting the bugs.


0.9.13 -> 0.9.14:
 *Increased the time the console meter is displayed in red from
  50ms to 2000ms. (when the recorded jack value is equal to or
  higher than 1.0.)
 *Added the -dBr argument to specify reference level when using
  the console dB meter.
 *Added the -mr argument to specify reference level when using
  the meterbridge meter.


0.9.12 -> 0.9.13:
 *Added peak indicators to the console meter. Code to do so taken
  from meterbridge by Steve Harris.
 *Updated --help and README with the new options.


0.9.11 -> 0.9.12:
 *Added option "-mt" to change meterbridge type. Current valid
  options are vu (default), ppm, dpm, jf or sco. Its not necesarry
  to specify "-mb" if using "-mt".
 *Added option "-dB" to get a dB meter for the console meter.


0.9.10 -> 0.9.11:
 *Added examples how to record ogg and mp3 files using the -ws option.
 *Decreased default buffersize from 60 to 20 seconds.
  (I even had trouble provocing underruns using a minimal
   0.05 seconds long buffer, so 60 seconds was obviously overkill)
 *Fixed message and error printing to stderr when
  vu meter is running.


0.9.9 -> 0.9.10:
 *Fixed segfault in case the --channels / -c argument is higher
  than the number of ports which is possible to connect to.
 *Added a terminal vu meter by default. It'll display red
  in case the recorded jack value is equal to or higher than 1.0.
  Use "-dv" to disable.
 *Added the --meterbridge / -mb option, which automatically
  starts Steve Harris' meterbridge (http://plugin.org.uk/meterbridge/)
  and constantly connects them to the same ports as jack_capture
  is connected to.

0.9.8 -> 0.9.9:
 *Added the --write-to-stdout / -ws option which writes 16 bit little endian
  sound to stdout. Code made by looking at jack-stdout.c by Robin Gareus.

0.9.7 -> 0.9.8:
 *Added the --print-formats / -pf option.
 *Replaced jack_client_new() with jack_client_open()

0.9.6 -> 0.9.7:
 *Don't segfault if the opening of a subsequent wav soundfile fails. (ie. if the 4GB limitation
  is reached on the old file and jack_capture continues writing on a new file.)

0.9.5 -> 0.9.6:
 *Fixed so that 2 channels are the default again, as supposed to. (bug was introduced
  in 0.9.4)

0.9.4 -> 0.9.5:
 *Fixed a bug that in some situations can cause segfault when
  jack buffer size is changed while recording.

0.9.3 -> 0.9.4:
 *Fixed bug that caused max 2 channels to be recorded.

0.9.2 -> 0.9.3:
 *Fixed horrible deadlock. Bug found by Ken Restivo.

0.9.1 -> 0.9.2:
 *Fix for a potensional deadlock.
 *Added the --silent/-s argument.
 *Some smaller fixes.

0.9.0 -> 0.9.1:
 *If recording to wav (the default) and the the 4GB limitation is reached,
  automatically close the file and continue writing to a new file with an
  autogenerated name.
 *Added the --version/-v argument.
 *Changed default number of zeros in the autogenerated filename to 1.

0.3.9 -> 0.9.0:
 *Better error output.
 *Autogenerate code to check if various formats are supported by sndlibfile.
 *Bumped version up to 0.9. jack_capture should reach a 1.0 state quite soon.
 *Changed the name of --recording-time to --duration to match -d.

0.3.8 -> 0.3.9:
 *Changed the -rt option name to -d, to be compatible with jackrec.
 *Do not stop recording in case of disk errors.
 *Got rid of deprecated libsndfile functions.
 *Added the --format/-f option. ("jack_capture -f flac", nice :-)  )
  (All sndfile formats are supported: http://www.mega-nerd.com/libsndfile/api.html#open)

0.3.7 -> 0.3.8:
 *Added the --recording-time option to stop recording after a certain number of seconds.
 *Quitting with CTRL-C/SIGINT writes remaining buffer to disk before ending program.

0.3.6 -> 0.3.7:
 *Fixed potentional buffer underrun error.

0.3.5 -> 0.3.6:
 *Fixed potentional ringbuffer size allocation miscalculation.
 *Better way to set leading zeros in filename. Thanks to Melanie.
 *Better underrun handling. Thanks to Dmitry Baikov.

0.3.4 -> 0.3.5:
 *Added support for jack buffer size change.
 *Removed some unnecessary code and comments
 *Beautified code a bit.

0.3.3 -> 0.3.4:
 *Fixed a bug in the reconnection code.
 *Beautified code a lot.

0.3.2 -> 0.3.3:
 *Changed bufsize argument to accept seconds instead of frames. Default buffer size is 60 seconds.
 *Improved documentation and help option.
 *Beautified source a bit.
 *Fixed bug in ringbuffer size allocation.

0.3.1 -> 0.3.2:
 *Fixed so that more than one instance of jack_capture can run at once.

0.3.0 -> 0.3.1:
 *Added the --port argument, which can be specified many times and accepts both input and output port names
 (including regexp expressions). This makes jack_capture to completely replace jackrec.

0.2.6 -> 0.3.0:
 *Rewrote buffer handling. Silence is now inserted when underruns occure. Previously, the
  file became shorter than the recording in case of underrun. It can still happen though, but
  much more seldom, and a warning about that will be printed to the terminal.
 *Removed last rests of jackrec code. Well, almost, at least.
 *Niceified code a lot.

0.2.5 -> 0.2.6:
 *Reduced CPU usage a lot because of better disk handling. (25% -> 1%)
 *Make sure the rest of the recorded file is not garbage in case of an overrun.
 *More efficient way of handling overruns.

0.2.4 -> 0.2.5:
 *Fixed really stupid compilation error. Thanks to Dragan Noveski for spotting it.

0.2.3 -> 0.2.4:
 *Give message to stderr during recording (not only after) if any overruns occur.
 *Do not delete file after recording if any overruns have occured. (stupid jackreq code #$!@$)
 *Increased default buffer size from 0.5M to 2M.

0.2.2 -> 0.2.3:
 *Added -z argument that choose number of leading zeros.
 *Various changes.

0.2.1 -> 0.2.2:
 *Only connect/disconnect ports if its necessary. This puts less stress on the jack system
  and possibly avoids never ending connect/reconnecting loops.
 *Replaced the timemachine-way of automatically setting filename by a much simpler one. Now the
  autogenerated filename is just jack_capture_<n>.wav: jack_capture_1.wav, jack_capture_2.wav, 
  jack_capture_3.wav and so on.
 *If jack is shut down during recording, stop the recording properly.
 *Various smaller changes.

0.2.0 -> 0.2.1:
 *Removed optional -f argument (that didn't work anyway) for setting the filename. Usage for program is now:
  "jack_capture [ -b bitdepth ] [-c channels] [ -B bufsize ] [filename]"
  Thanks to Cesare Marilungo for pointing out the bug.
 *Sound filename is also printed to the screen.

0.1.1 -> 0.2.0:
 *Automatically disconnect and connect ports while program is running. Previously, the
  connections where only set up when the program started.
 *Added make install.
 *Various smaller changes.
