NAME

       aj-snapshot - command line utility to store/restore ALSA and/or JACK connections to/from an XML file

SYNOPSIS

       aj-snapshot [ -adfjqrx ] [ -p polling_interval ] [ -i client_name ]... [ FILE ]

DESCRIPTION

       Aj-snapshot  is  a  small program that can be used to make snapshots of the connections made between JACK
       and/or ALSA clients. Because JACK can provide both audio and MIDI support to  programs,  aj-snapshot  can
       store  both  types of connections for JACK. ALSA, on the other hand, only provides routing facilities for
       MIDI clients. If you call aj-snapshot without any options, aj-snapshot will store all  current  ALSA  and
       JACK connections to FILE. The file will be an XML file, and you can use a text-editor if you want to edit
       it manually.

OPTIONS

       -a or --alsa

              Only store or restore ALSA midi connections. Also works in daemon mode.

       -d or --daemon

              Run  aj-snapshot  in  daemon  mode. Aj-snapshot will first try to restore the connections from the
              specified snapshot file. After this, it will wait for new ports to  be  registered  with  ALSA  or
              JACK.  Every  second  by  default,  aj-snapshot will check if new ports were registered in ALSA or
              JACK. When this is the case, it will try to restore the connections from your  snapshot  file.  If
              you  start  aj-snapshot  in  daemon mode, you don't need to specify the -r,--restore flag as it is
              implied anyway.

              If you send the HUP signal to the daemon, the daemon will reload the snapshot file. This gives you
              the possibility to trigger a connections restore. For an example  on  how  to  do  this,  see  the
              EXAMPLES  section below. When you combine the daemon mode with the -x,--remove option, sending the
              HUP signal to the daemon will clear all connections before restoring.

              When the JACK server is stopped (or crashes) while aj-snapshot runs in  daemon  mode,  aj-snapshot
              will  try  to keep running. When the JACK server is started again later, aj-snapshot will reattach
              automatically and restore your connections when needed.

       -f or --force

              When you try to save a snapshot over an existing file, aj-snapshot will ask you  if  you  want  to
              overwrite that file. With this option, you can force aj-snapshot to overwrite that file.

       -j or --jack

              Only store or restore JACK audio and midi connections. Also works in daemon mode.

       -p  interval

              Whenever  a  program  registers  a  port  with  ALSA  or  JACK,  aj-snapshot will see if there are
              connections in the snapshot file that should be  restored.  By  default,  aj-snapshot  will  check
              (poll)  if  there  are new ports every second (1000 milliseconds). With this option you can choose
              how often aj-snapshot should check for new ports. The value of interval  should  be  specified  in
              milliseconds.

       -q or --quiet

              Don't print any information about the connections that are stored or restored.

       -r or --restore

              When  you  specify the -r flag, aj-snapshot will try to restore all ALSA and JACK connections from
              FILE. (without it, aj-snapshot will try to store connections to FILE). You can combine this option
              with the -a or -j options, if you want to restore ALSA or JACK connections only.

       -x or --remove

              The -x option can be used when restoring connections, or when running in daemon  mode.  With  this
              option,  aj-snapshot will remove all existing connections before restoring the snapshot file. When
              you combine it with the -a or -j option, only the connections for the specific subsystem (ALSA  or
              JACK)  will  be removed. Without the -x option, aj-snapshot will try to restore connections on top
              of the connections that are already active.

              There is one more way in which you can use the -x option. If you call aj-snapshot without the FILE
              argument, you can use the -x option to remove all existing  ALSA  and  JACK  connections  (without
              doing anything else). As before you can combine it with the -a or -j options.

       -i  client_name

              You  can  use this option to name a client that should be ignored by aj-snapshot. You should write
              the exact name of the client after  the  -i  option.  If  that  name  contains  spaces,  or  other
              characters that have special meaning to the shell, you should put the name between single (safest)
              or  double  quotes.  To know the exact name of a client, you could save a snapshot and look up the
              name in the snapshot file. If you want to ignore multiple clients,  you  have  to  repeat  the  -i
              option with different client names (the maximum is 50 clients).

       -h or --help

              Print a short help message

EXAMPLES

       aj-snapshot test.snap

              Stores  a  snapshot of all current ALSA and JACK connections to a file called "test.snap". If that
              file already exists, aj-snapshot will ask you if you want to overwrite that file.

       aj-snapshot -r test.snap

              Restores all ALSA and JACK connections from the file "test.snap". This will leave any other active
              connections intact.

       aj-snapshot -xr test.snap

              Restore all ALSA and  JACK  connections  from  the  file  "test.snap",  but  remove  all  existing
              connections first.

       aj-snapshot -a test.snap

              Store all current ALSA connections to "test.snap".

       aj-snapshot -rj test.snap

              Restore  all  JACK  connections  from  "test.snap". This means that ALSA connections that might be
              stored in the file won't be restored.

       aj-snapshot -qfj test.snap

              Store all current JACK connections to "test.snap". Don't  print  any  info  on  standard  out  (be
              quiet), and forcibly overwrite "test.snap" if it already exists.

       aj-snapshot -ax

              Remove all ALSA connections

       aj-snapshot -d test.snap &

              Run  aj-snapshot  in daemon mode and make it a background process (&). Whenever a new ALSA or JACK
              client registers a port, connections from test.snap will be restored.

       aj-snapshot -djx test.snap &

              Run aj-snapshot in daemon mode for the JACK connections in "test.snap". Remove all  existing  JACK
              connections whenever the connections from test.snap are restored.

       1) aj-snapshot -d test.snap &
       2) aj-snapshot -f test.snap
       3) kill -HUP $(pidof aj-snapshot)

              1) First start up aj-snapshot in daemon mode with the file "test.snap".
              2)  After  some  connection  changes, a second instance of aj-snapshot (which is not run in daemon
              mode) overwrites that file with the new connections state.
              3) Send the HANGUP signal to the daemon to make it reload the file with the new connections  state
              (see 'man kill', and 'man pidof').

AUTHOR

       Written by Lieven Moors and Jari Suominen

REPORTING BUGS

       To report aj-snapshot bugs, or if you have feature requests:
       http://sourceforge.net/projects/aj-snapshot/

       Aj-snapshot home page:
       http://aj-snapshot.sourceforge.net/

       Clone the git repository:
       git clone git://gitorious.org/aj-snapshot/aj-snapshot.git

COPYRIGHT

       Copyright © 2009-2012 Lieven Moors and Jari Suominen.
       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
       This  is  free software: you are free to change and redistribute it.  There is NO WARRANTY, to the extent
       permitted by law.

Linux                                             NOVEMBER 2011                                   AJ-SNAPSHOT(1)