From e2de64d6f1beb9e492daf5b886e19933c1fa41dd Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdemultimedia@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/artsbuilder/tools.docbook | 735 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 735 insertions(+) create mode 100644 doc/artsbuilder/tools.docbook (limited to 'doc/artsbuilder/tools.docbook') diff --git a/doc/artsbuilder/tools.docbook b/doc/artsbuilder/tools.docbook new file mode 100644 index 00000000..417951df --- /dev/null +++ b/doc/artsbuilder/tools.docbook @@ -0,0 +1,735 @@ + + + +&arts; Tools + + +Included with &arts; is a number of utilities for controlling and +configuring its behavior. You need to have some familiarity with most of +these tools in order to use &arts; effectively. This section describes +each of the utilities and their command options. + + + +&kcontrol; + + +When running &arts; under &kde;, the &kcontrolcenter; provides a group +of control panel settings under the Sound +category. Some of these settings are used by &arts;. You can also +associate sounds with various window manager and &kde; events using the +Look & FeelSystem +Notifications panel. See the &kcontrol; manual +for information on using the panel settings. + + + + + +&artsd; + + +Access to the sound hardware resources is controlled by &artsd;, the +&arts; daemon. This allows different applications to simultaneously send +requests to the server, where they can be mixed together and +played. Without a centralized sound server a single application using a +sound device would prevent other applications from using it. + + + +To use &arts; there should be one and only one copy of &artsd; +running. It is typically run when &kde; starts up if it is enabled in +the &kcontrol; Sound Server panel. + + +The program accepts the following arguments: + + + + +artsd + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Set sampling rate to use. + + + + + + +Display command usage. + + + + + + +Enable network transparency. + + + + + + + +Set TCP port to use (implies +). + + + + + + +Public, no authentication (dangerous). + + + + + + +Enable full duplex operation. + + + + + +Specify audio device (usually /dev/dsp). + + + + + + +Set number of fragments. + + + + + + +Set fragment size, in bytes. + + + + + + +Set server auto-suspend time, in seconds. A value of zero +disables auto-suspend. + + + + + + +Specify the name of an application to be used to display error, +warning, and informational messages. If you are running KDE you can +use the artsmessage utility for this. + + + + + + + +Increase the size of network buffers to a value suitable for running over +a 10 mbps LAN. This is equivalent to using the -w 5 option (see below). + + + + + + + +When running artsd over a network connection +to another host you typically want to use a larger buffer size to +avoid dropouts. ARts provides applications with a suggested minimum +buffer size. Without this option the default size is based on the +fragment size * fragment count. Using this option you can increase +the size from the default by a factor of n. + + + + + + + +Set information level - 3 (quiet), 2 (warnings), 1 (info), 0 +(debug). + + + + + + +Display version level. + + + + + + +In most cases simply running &artsd; will suffice. + + + + +&artswrapper; + + +To provide good real-time response, &artsd; is usually run as a +real-time process (on platforms where real-time priorities are +supported). This requires root +permissions, so to minimize the security implications, &artsd; can be +started using the small wrapper program &artswrapper; which simply sets +real-time priority (running as root) and then executes &artsd; as a +non-root user. + + +If you make artswrapper SUID root, it will likely improve the quality +of your audio playback by reducing gaps in the music. However, it +also increases the risk that a bug in the code or a malicious user can +crash or otherwise harm your machine. In addition, on multi-user +machines, prioritizing high-quality audio may result in deteriorated +performance for the users who are trying to make +productive use of the machine. + + + + +&artsshell; + + +The &artsshell; command is intended as a utility to perform +miscellaneous functions related to the sound server. It is expected that +the utility will be extended with new commands in the future (see the +comments in the source code for some ideas). + + + +The command accepts the following format: + + + + + +artsshell + +suspendstatus +terminate +autosuspend secs +networkbuffers n +volume [volume] +stereoeffect options + + + + + + + +artsshell [options] command [command-options] + + +The following options are supported: + + + + + + + +Suppress all output. + + + + + + +Display command usage. + + + + + +The following commands are supported: + + + + + + + +Suspend the sound server. + + + + + + + +Display sound server status information. + + + + + + + +Terminate the sound server. This may confuse and/or crash any +applications that are currently using it. + + + + + + seconds + + +Set the autosuspend time to the specified number of seconds. The sound +server will suspend itself if idle for that period of time. A value of +zero disables auto-suspend. + + + + + + n + + +Set the size of the network buffers to be a factor of +n times the default size. + + + + + + [volume] + + +Sets volume scaling for sound server audio output. The +volume argument is a floating point +value. With no argument the current volume is displayed. + + + + + + + +List all of the available stereo effect modules. + + + + + name + +Insert a stereo effect into the stereo effect stack. Returns +an identifier that can be used for later removing it. It can be +installed at the top or the bottom (the default). + + + + + id + +Removes the stereo effect with identifier +id from the effects stack. + + + + + + + + +<application>artsplay</application> + +The artsplay command is a simple utility to +play a sound file. It accepts a single argument corresponding to the name of a +sound file which is sent to the sound server to be played. The sound +file can be any common sound file type such as wav or au. This utility is good for testing that the +sound server is working. By running two commands in parallel or in rapid +succession you can demonstrate how the sound servers mixes more than one +sound source. + + + + +<application>artsdsp</application> + + +The sound server only supports applications that are &arts;-aware. Many +legacy applications want to access the sound device directly. The +&artsdsp; command provides an interim solution that +allows most of these applications to run unchanged. + + + +When an application is run under &artsdsp; all accesses to the /dev/dsp audio device are intercepted and +mapped into &arts; API calls. While the device +emulation is not perfect, most applications work this way, albeit with +some degradation in performance and latency. + + +The &artsdsp; command follows the format: + + + + +artsdsp [options] application arguments + + + +The following options are recognized: + + + + + +, + +Show brief help. + + + + = name + +Use name to identify player to artsd. + + + + + + + +Emulate memory mapping (⪚ for Quake). + + + + + + +Show parameters. + + + + + + +A typical invocation is: + + + +artsdsp realplay song.mp3 + + + +Some applications work better with the +option. Not all features of the sound device are fully emulated, but +most applications should work. If you find one that does not, submit a +detailed bug report and the developers may be able to fix it. Again, +remember this is an interim solution and something of an ugly hack; the +best solution is to add native &arts; support to the applications. If +your favorite sound application does not have &arts; support, ask the +developer to provide it. + + + + + +<application>artscat</application> + + +This is a simple utility to send raw audio data to the sound server. +You need to specify the data format (sampling rate, sample size, and +number of channels). This is probably not a utility that you will use +often, but it can be handy for testing purposes. The command syntax is: + + + + + +artscat [ options ] [ filename ] + + + +If no file name is specified, it reads standard input. The following +options are supported: + + + + + sampling +rate + + +Set the sampling rate to use. + + + + + + bits + + +Set sample size to use (8 or 16). + + + + + + channels + + +Set number of channels (1 or 2). + + + + + + + + +Display command usage and exit. + + + + + + + + +&artscontrol; + + +This is a graphical utility for performing a number of tasks related to +the sound server. The default window displays two volume level +indicators and a slider to control overall output volume. From the +View menu you can select other functions: + + + + + +FFT Scope + + +Opens a window which shows a real-time spectrum analyzer style display. + + + + + +Audio Manager + + +Displays active sound sources and allows you to connect them to any of +the available busses. + + + + + +aRts Status + + +Shows if the sound server is running and if scheduling is +real-time. Indicates when server will autosuspend and allows you to +suspend it immediately. + + + + + +Midi Manager + + +Shows active &MIDI; inputs and outputs and allows you to make connections +[TODO: Does this work yet? Need more detail]. + + + + + +FreeVerb + + +Connects a FreeVerb reverb effect to the stack of &arts; output effects +and allows you to control the effect parameters graphically. + + + + + +Leds-like volume display + + +Changes the volume indicators in the main window to use a colored +LED display format instead of progress bars. + + + + + + + + + +<application>artsc-config</application> + + +This is a utility to assist developers using the &arts; C +API. It outputs the appropriate compiler and linker +options needed when compiling and linking code with &arts;. It is +intended to be used within make files to assist in portability. The +command accepts three options: + + + + + + + +Displays the compiler flags needed when compiling with the &arts; C +API. + + + + + + + + +Displays the linker flags needed when linking with the &arts; C +API. + + + + +--version + + +Displays the version of the artsc-config command. + + + + + +Typical output from the command is shown below: + + +% artsc-config +-I/usr/local/kde2/include/artsc +% artsc-config +-L/usr/local/kde2/lib -ldl -lartsc -DPIC -fPIC -lpthread +% artsc-config +0.9.5 + + + +You could use this utility in a make file using a rule such as: + + + +artsc: artsc.c + gcc `artsc-config --cflags` -o artsc artsc.c `artsc-config --libs` + + + + + +&mcopidl; + + +The &mcopidl; command is the &IDL; file compiler for &MCOP;, the +Multimedia Communication Protocol used by &arts;. Interfaces in &arts; +are defined in &IDL;, a language independent Interface Definition +Language. The &mcopidl; utility accepts an &IDL; file as input and +generates C++ header and source files for a class implementing the +interface. The command accepts the following syntax: + + + + +mcopidl [ options ] filename + + +The valid options are: + + + directory + + +Search in directory for includes. + + + + + + name + + +Exclude a struct, interface, or enum type name +from code generation. + + + + + + + + +Also create .mcoptype/.mcopclass files containing type information +for the &IDL; file. + + + + + + +More information about &MCOP; and &IDL; is covered in the section Interfaces and &IDL;. + + + + + -- cgit v1.2.1