<!-- 
<?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd">

To validate or process this file as a standalone document, uncomment
this prolog. Be sure to comment it out again when you are done -->

<chapter id="arts-tools">
<title
>Outils de &arts;</title>

<para
>&arts; est livré avec plusieurs outils pour contrôler et configurer son comportement. Ces outils doivent vous être familiers pour utiliser &arts; de façon efficace. Cette section décrit chaque utilitaire et ses options. </para>

<sect1 id="kde-control-center">
<title
>&centreConfiguration;</title>

<para
>Lorsque vous exécutez &arts; sous &kde;, le &centreConfiguration; fournit un groupe de réglages du centre de configuration dans la catégorie <guilabel
>Son</guilabel
>. Certains de ces réglages sont utilisés par &arts;. Vous pouvez aussi associer des sons avec des événements de &kde; et du gestionnaire de fenêtres en utilisant <menuchoice
><guilabel
>Apparence et ergonomie</guilabel
><guilabel
>Notifications du système</guilabel
></menuchoice
>. Lisez le manuel du &centreConfiguration; pour avoir des informations sur l'utilisation de ces réglages. </para>

</sect1>

<sect1 id="artsd">
<title
>&artsd;</title>

<para
>L'accès aux ressources matérielles pour le son est contrôlé par &artsd;, le démon de &arts;. Ceci permet à différentes applications d'envoyer simultanément des requêtes au serveur, où elles peuvent être mixées puis jouées. Sans un serveur sonore centralisé, une application utilisant le périphérique son empêche toutes les autres de l'utiliser. </para>

<para
>Pour utiliser &arts;, il doit y avoir une copie et une seule de &artsd; en fonctionnement. C'est typiquement le cas lorsque &kde; démarre si cela est activé dans <guilabel
>Serveur de son</guilabel
> dans le &centreConfiguration;. </para>

<para
>Le programme accepte les arguments suivants :</para>

<!-- LW: FIX THIS -->

<cmdsynopsis
><command
>artsd</command
> <group choice="opt"
> <option
>-n</option
> <option
>-p</option
> <option
>-N</option
> <option
>-W <replaceable
>n</replaceable
></option
> </group
> <group choice="opt"
> <option
>-a <replaceable
>audiomethod</replaceable
></option
> <option
>-r <replaceable
>sampling rate</replaceable
></option
> <option
>-b <replaceable
>bits</replaceable
></option
> <option
>-d</option
> <option
>-D <replaceable
>devicename</replaceable
></option
> <option
>-F <replaceable
>fragments</replaceable
></option
> <option
>-S <replaceable
>size</replaceable
></option
> <option
>-s <replaceable
>seconds</replaceable
></option
> <option
>-m <replaceable
>appName</replaceable
></option
> </group
> <group choice="opt"
> <option
>-h</option
> <option
>-A</option
> <option
>-v</option
> <option
>-l <replaceable
>level</replaceable
></option
> </group
> </cmdsynopsis>

<variablelist
><varlistentry>
<term
><option
>-r <replaceable
>taux d'échantillonnage</replaceable
></option
></term>
<listitem>
<para
>Règle le taux d'échantillonnage utilisé.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-h</option
></term>
<listitem>
<para
>Affiche l'utilisation des commandes.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-n</option
></term>
<listitem>
<para
>Active la transparence réseau.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-p <replaceable
>port</replaceable
></option>
</term>
<listitem>
<para
>Règle le port <acronym
>TCP</acronym
> à utiliser (implique <option
>-n</option
>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-u</option
></term>
<listitem>
<para
>Public, pas d'authentification (dangereux).</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-d</option
></term>
<listitem>
<para
>Active le mode full duplex.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><option
>-D <replaceable
>nom du périphérique</replaceable
></option
></term>
<listitem>
<para
>Spécifie le périphérique audio (habituellement <filename
>/dev/dsp</filename
>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-F <replaceable
>fragments</replaceable
></option
></term>
<listitem>
<para
>Règle le nombre de fragments.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-S <replaceable
>taille</replaceable
></option
></term>
<listitem>
<para
>Règle la taille des fragments, en octets.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-s <replaceable
>secondes</replaceable
></option
></term>
<listitem>
<para
>Règle la durée avant suspension automatique du serveur, en secondes. Une valeur nulle désactive la suspension automatique.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-m <replaceable
>Nom de l'application</replaceable
></option
></term>
<listitem>
<para
>Spécifie le nom de l'application qui sera utilisée pour afficher les erreurs, alertes et messages informatifs. Si vous exécutez KDE, vous pouvez utiliser l'utilitaire <application
>artsmessage</application
>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-N</option
></term>
<listitem>
<para
>Augmente la taille du tampon réseau à une valeur acceptable pour fonctionner sur un réseau local à 10 mbps. C'est équivalent à l'option -w 5 (voir plus bas). </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><option
>-w <replaceable
>n</replaceable
></option
></term>
<listitem>
<para
>Lorsque <application
>artsd</application
> est exécuté par une connexion réseau sur un autre hôte, il est recommandé d'utiliser un tampon de grande taille pour éviter des interruptions du son. ARts fournit des applications avec une taille de tampon minimale recommandée. Sans cette option, la taille par défaut est basée sur la taille des fragments * le nombre de fragments. En utilisant cette option, vous pouvez augmenter la taille par défaut par un facteur <replaceable
>n</replaceable
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-l <replaceable
>niveau</replaceable
></option
></term>
<listitem>
<para
>Règle le niveau d'information - 3 (muet), 2 (alertes), 1 (info), 0 (déboguage).</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-v</option
></term>
<listitem>
<para
>Affiche le numéro de version..</para>
</listitem>
</varlistentry>

</variablelist>

<para
>Dans la plupart des cas, exécuter simplement &artsd; suffira. </para>
</sect1>

<sect1 id="artswrapper">
<title
>&artswrapper;</title>

<para
>Pour avoir un bon temps de réponse, &artsd; est souvent exécuté en tant que processus temps-réel (sur les plates-formes gérant la priorité temps-réel). Ceci nécessite les droits <systemitem class="username"
>administrateur</systemitem
>, donc pour minimiser les problèmes de sécurité, &artsd; peut être lancé à l'aide d'un petit programme encapsulant, &artswrapper;, qui actionne simplement la priorité temps-réel (s'exécutant en tant qu'<systemitem class="username"
>administrateur</systemitem
>) et exécute ensuite &artsd; en tant qu'utilisateur non <systemitem class="username"
>administrateur</systemitem
>. </para>

<para
>Si vous rendez artswrapper SUID  <systemitem class="username"
>root</systemitem
>, ceci améliorera sensiblement la qualité de la lecture audio en réduisant les coupures dans la musique. Cependant, ceci augmente également le risque qu'un bogue dans le code ou qu'un utilisateur malicieux ne fasse planter ou bloquer votre machine. De plus, sur des machines multiutilisateurs, donner la priorité à un son de haute qualité peut diminuer les performances pour les utilisateurs qui essaient d'utiliser la machine de manière <quote
>productive</quote
>.</para>

</sect1>

<sect1 id="artsshell">
<title
>&artsshell;</title>

<para
>La commande &artsshell; est dédiée à exécuter des fonctions diverses liées au serveur de son. Cet utilitaire devrait être étendu dans le futur par l'ajout de nouvelles commandes (voir les commentaires dans le source). </para>

<para
>La commande s'utilise comme suit : </para>

<!-- LW: FIX THIS -->

<cmdsynopsis
><command
>artsshell</command
> <group
> <arg
>suspend</arg
><arg
>status</arg
> <arg
>terminate</arg
> <arg
>autosuspend <replaceable
>secs</replaceable
></arg
> <arg
>networkbuffers <replaceable
>n</replaceable
></arg
> <arg
>volume [<replaceable
>volume</replaceable
>]</arg
> <arg
>stereoeffect <replaceable
>options</replaceable
></arg
> </group
> <group
> <option
>-h</option
> <option
>-q</option
> </group
> </cmdsynopsis>

<para
>artsshell [options] <replaceable
>command</replaceable
> [<replaceable
>command-options</replaceable
>] </para>

<para
>Les options suivantes sont disponibles : </para>

<variablelist>

<varlistentry>
<term
><option
>-q</option
></term>
<listitem>
<para
>Supprime toute sortie.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-h</option
></term>
<listitem>
<para
>Affiche l'utilisation des commandes.</para>
</listitem>
</varlistentry>

</variablelist>

<para
>Les commandes suivantes sont disponibles :</para>

<variablelist>

<varlistentry>
<term
><option
>suspend</option
></term>
<listitem>
<para
>Suspend le serveur de son. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>état</option
></term>
<listitem>
<para
>Affiche les informations sur l'état du serveur de son.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>terminate</option
></term>
<listitem>
<para
>Arrête le serveur sonore. Ceci peut perturber ou faire planter toute application l'utilisant. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>autosuspend</option
> <parameter
>secondes</parameter
></term>
<listitem>
<para
>Règle la durée avant suspension automatique du serveur, en secondes. Le serveur sonore sera arrêté automatiquement s'il n'est pas sollicité durant cette période. Une valeur nulle désactive la suspension automatique. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>networkbuffers</option
> <parameter
>n</parameter
></term>
<listitem>
<para
>Règle la taille du tampon réseau à <parameter
>n</parameter
> fois la taille par défaut. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>volume</option
> [<replaceable
>volume</replaceable
>]</term>
<listitem>
<para
>Règle le volume de sortie du serveur audio. L'argument <replaceable
>volume</replaceable
> est une valeur de type flottant. Sans argument, le volume actuel est affiché. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>Liste des effets stéréo</option
></term>
<listitem>
<para
>Liste tous les modules d'effets stéréo disponibles.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>stereoeffect insert [top|bottom]</option
> <replaceable
>nom</replaceable
></term>
<listitem>
<para
>Insère un effet stéréo dans une pile d'effets stéréo. Retourne un identificateur qui peut être utilisé pour le supprimer plus tard. On peut l'installer en haut ou en bas (par défaut).</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>stereoeffect remove</option
> <replaceable
>id</replaceable
></term>
<listitem>
<para
>Supprime l'effet stéréo avec l'identificateur <replaceable
>id</replaceable
> de la pile d'effets.</para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="artsplay">
<title
><application
>artsplay</application
></title>

<para
>La commande <application
>artsplay</application
> est un simple utilitaire qui permet de lire un fichier son. Son seul argument est le nom du fichier son à envoyer au serveur sonore pour y être lu. Il peut être n'importe quel type de fichiers sons classique comme par exemple du type <literal role="extension"
>wav</literal
> ou <literal role="extension"
>au</literal
>. Ce programme est utile pour tester si le serveur sonore fonctionne bien. En exécutant deux commandes en parallèle, ou successivement, de manière rapide, on peut mettre en évidence le mixage de plusieurs sources sonores par le serveur.</para>

</sect1>

<sect1 id="artsdsp">
<title
><application
>artsdsp</application
></title>

<para
>Le serveur de son ne gère que les applications compatibles avec &arts;. Beaucoup d'applications héritées accèdent directement au périphérique son. La commande &artsdsp; fournit une solution intermédiaire qui permet à la plupart de ces applications de fonctionner sans changements. </para>

<para
>Lorsqu'une application est exécutée sous &artsdsp;, tous les accès au périphérique audio <filename class="devicefile"
>/dev/dsp</filename
> sont interceptés et transformés en appels aux <acronym
>API</acronym
> de &arts;. Cette émulation n'est pas parfaite, mais la plupart des applications fonctionnent de cette manière, avec une diminution des performances et des coupures. </para>

<para
>La commande &artsdsp; s'utilise comme suit : </para>

<!-- LW: FIX THIS -->
<para
>artsdsp [<replaceable
>options</replaceable
>] <replaceable
>arguments</replaceable
> </para>

<para
>Les options suivantes sont disponibles : </para>

<variablelist>

<varlistentry>
<term
><option
>-h</option
>, <option
>--help</option
></term>
<listitem>
<para
>De l'aide succincte.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><option
>-n</option
> <option
>--name</option
> = <replaceable
>nom</replaceable
></term>
<listitem>
<para
>Utilisez <replaceable
>nom</replaceable
> pour identifier le lecteur auprès de <command
>artsd</command
>.</para>

</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-m</option
> <option
>--mmap</option
></term>
<listitem>
<para
>Émule le memory mapping (&pex; pour <application
>Quake</application
>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-v</option
> <option
>--verbose</option
></term>
<listitem>
<para
>Affiche des paramètres.</para>
</listitem>
</varlistentry>

</variablelist>

<para
>Une invocation typique serait : </para>

<para>
<userinput
><command
>artsdsp</command
> <option
>-v</option
> <option
>-m</option
> <parameter
>realplay <replaceable
>song.mp3</replaceable
></parameter
></userinput>
</para>

<para
>Certaines applications fonctionnent mieux avec l'option <option
>--mmap</option
>. Les caractéristiques du périphérique sonore ne sont pas toutes émulées, mais la plupart des applications devrait fonctionner. Si vous trouvez une application qui ne fonctionne pas, envoyez un rapport de bogue détaillé et le développeur devrait être en mesure de régler le problème. Encore une fois, souvenez-vous que c'est une solution intermédiaire et peu élégante, la meilleure solution serait d'ajouter la gestion native de &arts; dans les applications multimédia. Si votre application favorite ne reconnaît pas &arts;, demandez au développeur d'y ajouter cette gestion. </para>

</sect1>

<sect1 id="artscat">
<title
><application
>artscat</application
></title>

<para
>C'est un simple utilitaire pour envoyer des données audio vers le serveur de son. Vous devez spécifier le format des données (taux d'échantillonnage, taille de l'échantillon, et nombre de canaux). Vous ne l'utiliserez probablement pas souvent, mais il peut rendre service pour certains tests. La syntaxe de la commande est la suivante : </para>

<!-- LW: FIX THIS -->
 
<para
>artscat [ <replaceable
>options</replaceable
> ] [ <replaceable
>fichier</replaceable
> ] </para>

<para
>Si aucun nom de fichier n'est spécifié, l'entrée standard est lue. Les options suivantes sont disponibles : </para>

<variablelist>
<varlistentry>
<term
><option
>-r</option
> <parameter
>taux d'échantillonnage</parameter
></term>
<listitem>
<para
>Règle le taux d'échantillonnage. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-b</option
> <parameter
>bits</parameter
></term>
<listitem>
<para
>Règle la taille des échantillons (8 bits ou 16 bits). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-c</option
> <parameter
>canaux</parameter
></term>
<listitem>
<para
>Règle le nombre de canaux (1 ou 2). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-h</option
></term>
<listitem>
<para
>Affiche l'utilisation de la commande et quitte. </para>
</listitem>
</varlistentry>

</variablelist>
</sect1>

<sect1 id="artscontrol">
<title
>&artscontrol;</title>

<para
>C'est un utilitaire graphique pour réaliser un certain nombre de tâches en rapport avec le serveur de son. La fenêtre par défaut affiche deux indicateurs de niveau de volume et une glissière pour contrôler le volume principal. À partir du menu <guimenu
>Affichage</guimenu
>, vous pouvez sélectionner d'autres fonctions : </para>

<variablelist>

<varlistentry>
<term
><guimenuitem
>FFT</guimenuitem
></term>
<listitem>
<para
>Ouvre une fenêtre qui affiche un analyseur de spectre en temps réel. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>Gestionnaire audio</guimenuitem
></term>
<listitem>
<para
>Affiche les sources sonores actives et vous permet de les connecter aux bus disponibles. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>État de aRts</guimenuitem
></term>
<listitem>
<para
>Montre si le serveur sonore est actif et s'il s'exécute avec la priorité temps-réel. Il indique lorsque le serveur est suspendu automatiquement, et permet de le suspendre immédiatement. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>Gestionnaire Midi</guimenuitem
></term>
<listitem>
<para
>Affiche les entrées et sorties &MIDI; actives et vous permet de faire des connexions [à faire : Est-ce que ça marche ? Besoin de plus de détails]. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>FreeVerb</guimenuitem
></term>
<listitem>
<para
>Connecte une réverbération FreeVerb à la pile des effets de sortie de &arts; et vous permet de contrôler les paramètres de l'effet de manière graphique. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>Affichage du volume sous forme de LED</guimenuitem
></term>
<listitem>
<para
>Utilise des diodes électroluminescentes (<acronym
>LED</acronym
>) colorées pour les indicateurs de volume de la fenêtre principale à la place des barres de progression. </para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="artsc-config">
<title
><application
>artsc-config</application
></title>

<para
>C'est un utilitaire pour aider les développeurs à utiliser les <acronym
>API</acronym
> C de &arts;. Il donne les options du lieur et du compilateur nécessaires pour compiler et lier du code avec &arts;. Il est destiné à être utilisé dans des makefiles pour favoriser la portabilité. La commande accepte trois options : </para>

<variablelist>
<varlistentry>
<term
><option
>--cflags</option
></term>
<listitem>
<para
>Affiche les options de compilation nécessaires pour compiler avec les <acronym
>API</acronym
> C de &arts;.. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>--libs</option
></term>
<listitem>
<para
>Affiche les options de compilation du lieur nécessaires pour compiler avec les <acronym
>API</acronym
> C de &arts;.. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><acronym
>--version</acronym
></term>
<listitem>
<para
>Affiche la version de la commande <command
>artsc-config</command
>. </para>
</listitem>
</varlistentry>
</variablelist>

<para
>Voici la sortie typique de la commande :</para>

<screen width="40"
><prompt
>%</prompt
> <userinput
><command
>artsc-config</command
> <option
>--cflags</option
></userinput>
<computeroutput
>-I/usr/local/kde2/include/artsc</computeroutput>
<prompt
>%</prompt
> <userinput
><command
>artsc-config</command
> <option
>--libs</option
></userinput>
<computeroutput
>-L/usr/local/kde2/lib -ldl -lartsc -DPIC -fPIC -lpthread</computeroutput>
<prompt
>%</prompt
> <userinput
><command
>artsc-config</command
> <option
>--version</option
></userinput>
<computeroutput
>0.9.5</computeroutput
>
</screen>

<para
>Vous auriez pu utiliser cet utilitaire dans un makefile en utilisant une règle telle que : </para>

<programlisting
>artsc : artsc.c
        gcc `artsc-config --cflags` -o artsc artsc.c `artsc-config --libs`
</programlisting>

</sect1>

<sect1 id="mcopidl">
<title
>&mcopidl;</title>

<para
>La commande &mcopidl; est le compilateur &IDL; pour &MCOP;, le protocole de communication multimédia utilisé par &arts;. Les interfaces dans &arts; sont définies en &IDL;, un langage de définition d'interface (<foreignphrase
>Interface Definition Language</foreignphrase
>) indépendant du langage. L'utilitaire &mcopidl; accepte en entrée un fichier &IDL; et génère des fichiers d'en-tête et de sources C++ pour une classe implantant l'interface. La commande a la syntaxe suivante : </para>

<!-- LW: FIX THIS -->

<para
>mcopidl [ <replaceable
>options</replaceable
> ] <replaceable
>fichier</replaceable
> </para>

<para
>Les options disponibles sont :</para>
<variablelist>
<varlistentry>
<term
><option
>-I</option
> <parameter
>dossier</parameter
></term>
<listitem>
<para
>Cherche les fichiers d'inclusion dans <parameter
>dossier</parameter
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-e</option
> <parameter
>nom</parameter
></term>
<listitem>
<para
>Exclut le type de struct, interface, ou enum <parameter
>nom</parameter
> de la génération du code. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>-t</option
></term>
<listitem>
<para
>Crée aussi les fichiers <literal role="extension"
>.mcoptype</literal
>/<literal role="extension"
>.mcopclass</literal
> contenant les informations de type pour le fichier &IDL;. </para>
</listitem>
</varlistentry>
</variablelist>

<para
>Vous trouverez plus d'informations à propos de &MCOP; et &IDL; dans la section <link linkend="interfaces"
>Interfaces et &IDL;</link
>. </para>

</sect1>

</chapter>