jack_capture V0.9.57
Released 2009-08-24
Kjetil S. Matheussen
ABOUT
*****
jack_capture is a program for recording soundfiles with jack.
The default operation of the program is executed by writing "jack_capture"
in the terminal without any extra command line options:
$ jack_capture
...which will record what you hear in your loudspeakers
into a stereo wav file.
Other features:
* Autogenerated filenames are unique and humanly readable.
* The 4GB size barrier for wav files is handled by continuing
writing to new files when reaching 4GB.
* Supports all soundfile formats supported by sndfile.
(wav, aiff, ogg, flac, wavex, au, etc.) (option: -f <format>)
* Supports mp3 by using liblame. (option: -mp3)
* Option for writing raw 16 bit data to stdout. (option: -ws)
* Built-in console meter, plus option for automatically starting and stopping
the Meterbridge jack meter program. Port connections to Meterbridge
are done automatically, and on the fly, by jack_capture.
* jack_capture can connect to any input or output jack port.
When "connecting" to a jack input port (i.e. a writable port), jack_capture
constantly monitors which jack ports which are connected
to that input port, and makes sure jack_capture is always
connected to the same ports.
In other words, jack_capture will reconnect its ports automatically during
recording to match the connections of the ports.
This is for instance convenient when recording the playback ports since
jack_capture can be started first, and then other programs can start
and stop at any moment while all sound still should be recorded.
* No limit on the number of jack ports jack_capture can connect to.
(I.e. the --port argument can be specified more than once, plus that
it accepts wildcard arguments. For instance, jack_capture --port "*" will
connect to all current jack ports, both input and output ports, except
jack_capture's own ports.)
* Buffers are automatically increased during runtime to prevent
underruns and to avoid wasting memory by preallocating too much.
* The disk thread is automatically reniced to a higher priority when
using more than half of the buffer.
* Significantly better recording performance than Ardour. (probably because
jack_capture writes all channels into only one file and that it is
not creating peak files). (tested on athlonXP)
* No problem writing at least 256 channels of 32 bit wav at once to a
local hard drive. (tested on icore7)
COMMON USAGE
************
$ jack_capture
ADVANCED USAGE
**************
jack_capture [--bitdepth n] [--channels n] [--port port] [filename]
[ -b n] [ -c n] [ -p port]
"bitdepth" is by default FLOAT. It can be set to either 8, 16, 24 or 32. (for relevant formats)
"channels" is by default 2.
"port" is by default set to the two first physical outputs. The "port" argument can be
specified more than once.
"filename" is by default auotogenerated to "jack_capture_<number>.<format>"
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] -> Selects fileformat provided by snfile.
See http://www.mega-nerd.com/libsndfile/api.html#open
(Default is wav for 1 or 2 channels, and wavex for more than 2.)
[--print-formats] or [-pf] -> Prints all sound formats provided to sndfile 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.
[--mp3] or [-mp3] -> Writes to an mp3 file using liblame (LAME).
(the --format option has no effect using this option)
[--mp3-quality n] or [-mp3q n] -> Selects mp3 quality provided by liblame. n=0 is best, n=9 is worst.
Default n is 2. (0 uses the most amount of CPU, 9 uses the least)
[--mp3-bitrate n] or [-mp3b n] -> Selects mp3 bitrate (in kbit/s).
Default is set by liblame. (currently 128)
[--write-to-stdout] or [-ws] -> Writes 16 bit little endian to stdout. (the --format option, the
--mp3 option, and some others have no effect using this option)
[--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".
[--linear-meter] or [-lm] -> Use linear scale for the console meter (default is dB scale)
[--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.
[--jack-transport]/[-jt] -> Start program, but do not start recording until jack transport has started rolling
rolling. When jack transport stops, the recording is stopped, and the program ends.
[--jack-transport-multi]/[-jtm] -> Similar to --jack-transport, but do not end program when jack transport stops.
Instead, record to a new file when jack_transport start rolling again.
(not implemented yet)
[--bufsize s] or [-B s] -> Initial/minimum buffer size in seconds. Default is 8 seconds
for mp3 files, and 4 seconds for all other formats.
[--maxbufsize] or [-MB] -> Maximum buffer size in seconds. jack_capture will allocate.
Default is 40. (Buffer is automatically increased during
recording when needed. But it will never go beyond this size.)
[--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 ogg format:
$jack_capture -f ogg
To record a stereo file of what you hear in the mp3 format:
$jack_capture -mp3
To record a stereo file of what you hear in the wav format:
$jack_capture --port system:playback_1 --port system:playback_2
****************************************************************************
**** NOTE! The above example does _exactly_ the same as the default!!! ****
****************************************************************************
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/
Code for writing to stdout was made by looking at http://mir.dnsalias.com/oss/jackstdout/start
made by Robin Gareus.
CHANGES
*******
0.9.56 -> 0.9.57
* Applied gcc 4.5 linking order fix from Alessio Treglia.
* Changed march=native to mtune=native
0.9.55 -> 0.9.56
* Fix for possible error when trying to connect to a non-existing port.
0.9.54 -> 0.9.55
* Don't hardcode meterbridge path during compilation. Thanks to Adrian Knoth
for fix.
* Avoid killing random process at exit in case meterbridge couldn't be started.
0.9.53 -> 0.9.54
* Removed jack_capture_gui from the target list since it uses Xdialog,
which again belongs to a package requiring gtk1. (This should make
things simpler for package managers)
* Made meterbridge optional.
0.9.52 -> 0.53
* Added the option --filename-prefix / -fp for setting the prefix for
autogenerated filenames. The default is "jack_capture_".
* Made jack_capture_gui2 use the -fp option to avoid overwriting files
from older sessions.
* Changed jack_capture_gui2 to use "-f ogg" instead of piping through
oggenc. Did not do the same change for mp3 files, since liblame is
not always available.
* Added code to jack_capture_gui2 to create uniqe filenames when creating
mp3 files.
0.9.51_beta -> 0.9.52
* Smaller fixes
* Crashfix for exit handling. (introduced in 0.51_beta)
0.9.50 -> 0.51_beta
* Smaller reorganizing of buffer handling, disk handling and exit handling.
0.9.49 -> 0.50
* Only print warning if unable to set nice value less than 0. (-10 is okay now)
* Added JackPortIsTerminal as jack port flag.
* Various cleanups.
0.9.48 -> 0.9.49
* Let the jack process thread trigger the buffer check thread instead of using
usleep.
* Added the -jt option to let jack transport trigger when to start and stop recording.
0.9.47 -> 0.9.48
* Fixed possible bug when finishing the recording if user has specified a duration.
* When allocating buffer, do not zero it out, only touch all pages belonging to
it to make sure all memory is mapped into physical memory before it is used
by the realtime process. This avoids hogging the memory bus unnecessarily.
The first 8 blocks are still zeroed out during initialization though, for
the CPU cache. (Might create a less shocking startup.)
* Push back the '\n' character after reading it from stdin. For some unknown
reason this seems to fix the occational problem of mixed up characters in
the console when exiting. (if only ncurses worked in non-fullscreen mode...)
0.9.46 -> 0.9.47
* Only call sem_post if waiting. In extremely extreme situations, this avoids
the sem value to overflow. Don't know what happens then.
0.95_beta -> 0.9.46:
* Smaller cleanups.
* Reduced chance of cache misses in the buffering scheme.
0.9.44 -> 0.9.45_beta:
* Replaced the two lockless fifo/lifo queues with three lockless ringbuffers. (CPUs without
CAS2 instruction are now supported.)
* Only increase buffer by two blocks at the time between soundcard interrupts. This should
decrease the chance of jack_capture hogging the memory bus for too long. (Which in theory
can lower the chance of xruns in memory intensive realtime processes.)
* Changed buffering incrementing scheme. If, at any time, the amount of free buffer is smaller than
the initial buffer size, increase the buffer a little bit. Only do this if the buffer is
less than maxbuffer. Buffer is never decreased.
* Replaced all posix pthread_cond variables with posix semaphores. Far simpler code and
much easier to understand.
0.9.43 -> 0.9.44:
* Increased default buffer time from 4 seconds to 8 seconds for mp3 files.
(Saw more than 1 second of the buffer was used one time in the start of
the recording on a very fast machine. Buffer was increased automatically
as supposed to, but the default init buffer size is increased anyway
just in case.)
0.9.42 -> 0.9.43:
* Fixed correct autogenerated file suffix for mp3 files.
0.9.41 -> 0.9.42:
* Updated --advanced-help option and README file
0.9.40 -> 0.9.41:
* Added missing link libraries to the makefile. Caused by Fedora not
supporting indirect linking anymore. Patch from Orcan Ogetbil.
(https://fedoraproject.org/wiki/UnderstandingDSOLinkChange)
* Applied patch from Orcan Ogetbil to fix 64 bit PowerPC compilation.
0.9.39 -> 0.9.40:
* Made "-f mp3" do the same as "-mp3". ("-mp3" still works)
0.9.38 -> 0.9.39:
* Reduced default buffering time from 10 to 4 seconds. (Buffering time
can probably safely be set below 1 second with the new buffer monitor
thread)
* Also increase buffer when more than 1/4 of the buffer is used
and the unused buffer time is less than 5 seconds. (This in addition
to always increase buffer when more than half of it is used)
* Fixed console update and keyboard handling.
0.9.37 -> 0.9.38:
* Added the --mp3-bitrate option.
* Renamed --lame-quality to --mp3-quality.
* Use a new dedicated high-priority SCHED_OTHER thread to monitor buffer status.
Buffer status was previously only checked in the disk thread, but since the
disk thread might stall for longer periods, it is not an ideal place to do this.
* Replaced the --help output with a much simpler text, making it clearer that extra
options are normally not needed. Also added the --advanced-options option, which
displays the contents of the old --help option.
* Fix --help a bit
0.9.36 -> 0.9.37:
* Print warning in case nice value in /etc/security/limits.conf is set
to -10 instead of -20.
* Added support for mp3 files. Requires liblame. Not very well tested yet.
Note that jack_capture also compiles without liblame installed.
(should be practical for package distributors who can not make
jack_capture depend on liblame). There is no runtime linking to
liblame yet though, so mp3 files are not supported unless libmp3lame.so
+ lame/lame.h is installed when jack_capture is compiled.
* Check whether sndfile supports ogg during compilation. (Avoid having
to edit the Makefile when using an older version of sndfile)
* Better screen clean-up at shutdown. (Not working very well yet, maybe
ncurses should be used instead of manually sending escape sequences?)
0.9.35 -> 0.9.36:
* Add support for OGG (requires sndlib>=1.0.18)
* Check if file format is supported by sndlib before creating file
* Added auto-support for WVE, MPC2K and RF64. (untested)
0.9.34 -> 0.9.35:
* Reset terminal colors when exiting.
* Check dependencies for various programs in the Makefile
* Tried to make it even more clear (if that's possible) that
'jack_capture --port system:playback_1 --port system:playback_2'
does exactly the same as the default.
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.
*Check if sndfile.h exists 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.