jack_capture V0.9.73 Released 2017-05-19 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, opus, flac, wavex, au, etc.) (option: -f
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 autogenerated to "jackcapture
Additional arguments: [--recording-time n] or [-d n] -> Recording is stopped after "n" seconds. This options also starts jack_capture in --no-stdin mode. To stop recording before the timeout, one can press Ctrl-C.) [--filename-prefix s]/[-fp n] -> Sets first part of the autogenerated filename. (default is "jackcapture") [--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 libsndfile. See http://www.mega-nerd.com/libsndfile/api.html#open This option will overwrite any format specified by the output filename. (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] -> Suppresses some common messages printed to the terminal. [--absolutely-silent] or [-as] -> Suppresses all messages printed to the terminal. Warning: libraries used by jack_capture may still print messages. [--verbose] or [-V] -> Prints some extra information to the terminal. [--mp3] or [-mp3] -> Writes to an mp3 file using liblame (LAME). This option will overwrite any format specified by the output filename. (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 updates in the console. [--disable-console] or [-dc] -> Disable console updates. Same as "-dm -hbu". [--no-stdin] or [-ns] -> Don't read the console. (i.e pressing return won't stop recording.) [--daemon] -> Same as writing "--no-stdin --absolutely-silent". [--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 When jack transport stops, the recording is also 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 starts rolling again. (not implemented yet) [--jack-freewheeling]/[-jf] -> Start program, but do not start recording until jack enters freewheeling mode When jack leaves freewheeling, the recording is also stopped, and the program ends. [--manual-connections]/[-mc] -> jack_capture will not connect any ports for you. [--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. Beware that you might risk overwriting an old file by using this option. To only set prefix, use --filename-prefix / -fp instead. (It's usually easier to set last argument instead of using this option) [--osc] or [-O] -> Specify OSC port number to listen on. see --help-osc [--timestamp] or [-S] -> create a FILENAME.tme file for each recording, storing the system-time corresponding to the first audio sample. [--rotatefile N] or [-Rf N] -> force rotate files every N audio-frames. [--hook-open c] or [-Ho c] -> command to execute on successful file-open. (see below) [--hook-close c] or [-Hc c] -> command to execute when closing the session. (see below) [--hook-rotate c] or [-Hr c] -> command to execute on file-name-rotation. (see below) [--hook-timing c] or [-Ht c] -> callback when first audio frame is received. (see below) [--timemachine] or [-tm] -> jack_capture operates in "timemachine" mode. [--timemachine-prebuffer s] -> Specify (in seconds) how long time to prebuffer in timemachine mode. [ -tmpb s] -> ------------------------ "" ----------------------------------------
All hook options take a full-path to an executable as argument.
The commands are executed in a fire-and-forget style upon internal events.
All output of the hooks is discarded.
Paramaters passed to the hook-scripts:
open: CMD
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 named stereo file of what you hear in the ogg format: $jack_capture output.ogg
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*
BUILD
make
INSTALL
PREFIX=/usr/local make install
ACKNOWLEDGMENT
Originally based on the jackrec program in the jack distribution made by Paul Davis 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.
Code contributions from: Florian Faber, Robin Gareus, Adrian Knoth, Filipe Lopes, Svend-Erik Kjær Madsen (made jack_capture_gui), Hermann Meyer (made jack_capture_gui2), Dan Muresan, Orcan Ogetbil, and Alessio Treglia.
Thanks to the following for helping to fix bugs, report bugs, give suggestions, etc.: Fons Adriaensen, Gabriel J.L. Beckers, Julien Claassen, Dominique Fober, Peder Hedlund, Cesare Marilungo, Jaromír Mike¨, Dragan Noveski, Andras Simon, and Anders Vinjar.
CHANGES
0.9.72 -> 0.9.73
0.9.71 -> 0.9.72
0.7.70 -> 0.9.71
0.9.69 -> 0.9.70
0.9.67 -> 0.6.69
0.9.66 -> 0.9.67
0.9.65 -> 0.9.66
0.9.64 -> 0.9.65
0.9.63 -> 0.9.64
0.9.62 -> 0.9.63
0.9.61 -> 0.9.62
0.9.60 -> 0.9.61
0.9.59 -> 0.9.60
0.9.58 -> 0.9.59
0.9.57 -> 0.9.58
0.9.56 -> 0.9.57
0.9.55 -> 0.9.56
0.9.54 -> 0.9.55
0.9.53 -> 0.9.54
0.9.52 -> 0.53
0.9.51_beta -> 0.9.52
0.9.50 -> 0.51_beta
0.9.49 -> 0.50
0.9.48 -> 0.9.49
0.9.47 -> 0.9.48
0.9.46 -> 0.9.47
0.95_beta -> 0.9.46:
0.9.44 -> 0.9.45_beta:
0.9.43 -> 0.9.44:
0.9.42 -> 0.9.43:
0.9.41 -> 0.9.42:
0.9.40 -> 0.9.41:
0.9.39 -> 0.9.40:
0.9.38 -> 0.9.39:
0.9.37 -> 0.9.38:
0.9.36 -> 0.9.37:
0.9.35 -> 0.9.36:
0.9.34 -> 0.9.35:
0.9.33 -> 0.9.34:
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.
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. It's 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 it's 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 jackcapture
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.