<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kmyapplication "<application
>Sam</application
>">
  <!ENTITY kappname "&kmyapplication;">
  <!ENTITY package "kde-module">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">

]>
<book id="sam" lang="&language;">

<bookinfo>

<othercredit role="translator"
><firstname
>Innocenzo</firstname
><surname
>Ventre</surname
><affiliation
><address
><email
>innocenzo.ventre@gmail.com</email
></address
></affiliation
><contrib
>Traduzione italiana</contrib
></othercredit
> 


<date
>2012-12-13</date>
<releaseinfo
>0.4</releaseinfo>

<abstract>
<para
>&kmyapplication; è un gestore di di modelli acustici. </para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>kdeutils</keyword>
<keyword
>Kapp</keyword>
<keyword
>Simon</keyword>
<keyword
>Riconoscimento</keyword>
<keyword
>pronuncia</keyword>
<keyword
>voce</keyword>
<keyword
>comando</keyword>
<keyword
>controllo</keyword>
<keyword
>modello</keyword>
<keyword
>compilazione</keyword>
<keyword
>Sam</keyword>
<keyword
>accessibilità</keyword>
</keywordset>

<legalnotice
>&FDLNotice;</legalnotice>

<copyright>
<year
>2009-2012</year>
<holder
>Peter Grasch</holder>
</copyright>

<authorgroup>
<author
><personname
> <firstname
>Peter</firstname
> <othername
>H.</othername
> <surname
>Grasch</surname
> </personname
> <email
>peter.grasch@bedahr.org</email
> </author>
</authorgroup>


<title
>Manuale di &kmyapplication;</title>
</bookinfo>

<chapter id="introduction">
<title
>Introduzione</title>

<para
>&kmyapplication; is a tool to create and test acoustic models. It can compile new speech models, use models created by Simon and produce models that can be used by Simon later on.</para>
<para
>It is targeted towards people wanting more control over their acoustic model and provides much lower level access to the build process. &kmyapplication; is mainly geared towards speech professionals wanting to improve and / or test their acoustic model.</para>
<para
>For more information on the architecture of the Simon suite please see the <ulink url="help:/simon/overview.html#architecture"
>Simon manual</ulink
>.</para>

<sect1 id="background">
  <title
>Informazioni di base</title>

  <para
>Questa sezione fornisce qualche informazione di base per la compilazione ed il processo di testing.</para>

<sect2 id="effective_testing">
  <title
>Collaudo</title>
  <para
>One of the major features of Sam is to test the generated acoustic models.</para>

  <para
>La procedura di test di base è quella di eseguire il riconoscimento su campioni di cui la trascrizione è già nota e confrontandone i risultati. &kmyapplication;, prende anche il punteggio di confidenza del riconoscimento in considerazione per valutare la robustezza del sistema creato.</para>

  <para
>A causa del modo con cui vengono creati i modelli acustici, sia la precisione di riconoscimento che la fiducia saranno molto asimmetriche quando gli stessi campioni sono utilizzati sia per la formazione che per i test. Questa modalità è nota come testing «in corpus» (i campioni utilizzati per le prove sono anche nella  formazione «in corpus»).</para>

  <para
>Mentre i test «in corpus» potrebbero dirti se il processo di compilazione fallisce o produce dei risultati secondari, non ti dirà il «reale» tasso di riconoscimento del modello creato. Pertanto è utile fare test «fuori corpus»: utilizza campioni diversi per la formazione e per i test.</para>
  <para
>Per semplici test «fuori corpus» dividi le istruzioni in due parti: una usata per compilare il modello ed una usata per testare il modello. Naturalmente l'insieme dei test non deve essere troppo grande per ottenere un risultato rappresentativo.</para>
  <para
>Se non hai molti dati di prova, puoi anche dividere il corpus completo in dieci parti. Compilare 10 modelli, ognuno lasciando fuori una parte dal corpus. Quindi eseguire poi i singoli test (sempre con il set di test che è stato escluso durante la compilazione) e la media dei risultati.</para>

</sect2>
</sect1>

</chapter>

<chapter id="using-kapp">
<title
>Uso di &kmyapplication;</title>

<para
>&kmyapplication; fornisce un'interfaccia grafica che è suddivisa in cinque aree.</para>

<para>
<screenshot>
<screeninfo
>Finestra principale</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="main.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase
>Finestra principale</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>

<para
>The order of the tabs represents a complete Sam workflow from creating a model to testing it. </para>

<sect1 id="input_output">
  <title
>File in ingresso &amp; in uscita</title>

  <para
>Specifica i file su cui lavorare. Puoi salvare e caricare la configurazione usando rispettivamente i pulsanti <guibutton
>Salva</guibutton
> e <guibutton
>Carica</guibutton
>.</para>
<warning>
    <para
><emphasis
>Solo</emphasis
> i menu <guibutton
>Salva</guibutton
> e <guibutton
>Carica</guibutton
> salvano i percorsi e le opzioni definite. Non salvano i file associati.</para>
</warning>

<para
>Here you also have the option to select between supported model compilation / test backends. Depending on your Simon installation, not all might be available.</para>

<para>
<screenshot>
<screeninfo
>Selezione ingresso &amp; uscita</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="input_output.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase
>Selezione ingresso &amp; uscita</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>

<para
>If you want to compile and / or test the Simon model, you can use the <guibutton
>Modify Simon's model</guibutton
> option to load the appropriate files. Both scenarios and prompts will be serialized as appropriate.</para>

<para
>When Simon compiles the model, it will automatically remove untrained words during serialization as well as adapting the prompts appropriately. This will also happen when selecting <guibutton
>Modify Simon's model</guibutton
>. If you do, however serialize them separately using <guibutton
>Serialize scenarios</guibutton
> and <guibutton
>Serialize prompts</guibutton
> this adaption will not be performed and you alone are responsible for the validity of the input files. If you provide file names directly this of course applies even more so.</para>

<para
>When selecting a static model as the used model type &kmyapplication; will still compile the language model, just like Simon would. It also copies the given base model input files to the output paths.</para>

<para
>&kmyapplication; allows the user to provide different types of prompts files for the creation and the testing of the model. For more information about how to use this feature effectively, please refer to the section on <link linkend="effective_testing"
>effective testing</link
>. </para>

<para>
<screenshot>
<screeninfo
>Test configuration</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="sam_test_io.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase
>Test configuration</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>

<para
>Users can set up an arbitrary number of test configurations to compare different model parameters. All configured tests will be run and all are listed in any reports that might be exported. Through the option of supplying different input files than the compiled model, reference models (baselines) can be included in the report. </para>

<para
>Since Simon 0.4, the primary file format for models is the newly introduced SBM format. While Sam will also create SBM models, the testing still requires low level input files. This may seem counter intuitive but presents certain advantages in practice: The Simon model compilation (and thus also the SAM model compilation) still builds the low level output files for both SPHINX and HTK model compilers before packaging them into SBMs so pointing SAM to these (temporary) files is not difficult and in fact the default when using <guibutton
>Modify Simon's model</guibutton
>. Because acoustic model compilation is typically an iterative process, the compiler typically produces multiple temporary versions of different stages of parameter estimation. By allowing low level input, testing and comparing these intermediate results is much easier. </para>
<para
>If you want to test a model you received as a SBM container, you can extract it with SAM through the <guibutton
>Extract Simon Model</guibutton
> option to gain access to the low level input files required for testing with &kmyapplication;. </para>

</sect1>

<sect1 id="conservative_training">
<title
>Conservative Training</title>
<para
>If you have <ulink url="help:/simond/using-kapp.html#User_Configuration"
>configured Simond to keep recognition samples</ulink
>, Sam can import this data through the <guibutton
>Import recognition samples</guibutton
> option in the "Input &amp; output" section.</para>

<para>
<screenshot>
<screeninfo
>Conservative training</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="conservative_training.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase
>Conservative training</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>

<para
>The label of the prompts file will be built automatically from the most likely recognition result. You can limit the selection to only include samples that achieved a given confidence score.</para>

<para
>If the Simon setup you're importing the samples from uses a <ulink url="help:/simon/commands.html#filter_command_plugin"
>global filter to deactivate recognition</ulink
>, then you can provide Sam with the command that activates and deactivates this filter (pausing and resuming the recognition, respectively) to ignore any samples produced while the recognition was deactivated.</para>
</sect1>

<sect1 id="adapt_scenarios">
  <title
>Scenari adatti</title>

  <para
>Simon stores the language model in scenarios. When you want to use them to compile the model, you first need to serialize them to files readable by SPHINX or Julius and the HTK.</para>

<para>
<screenshot>
<screeninfo
>Scenari adatti</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="adapt_scenarios.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase
>Scenari adatti</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>

  <para
>To do this, select <guibutton
>Serialize scenarios</guibutton
> button in the <link linkend="input_output"
>Input &amp; output tab</link
>. Simon's scenarios will also be serialized when using the <guibutton
>Modify Simon's model</guibutton
> options.</para>

  <para
>In questa pagina puoi trovare le informazioni sullo stato dell'adattamento ed in caso di errore, leggere dettagliati messaggi di errore.</para>
</sect1>

<sect1 id="build_model">
  <title
>Creare il modello</title>

  <para
>Qui puoi costruire il modello usando i file d'ingresso e di uscita definiti nella <link linkend="input_output"
> sezione entrate &amp; uscite</link
>.</para>

  <para
>The compilation process is identical to the one used by Simond. Unlike Simond, however, the full log of all called external programs, their output as well as progress information is shown regardless of whether the compilation was successful or not.</para>

<para>
<screenshot>
<screeninfo
>Creare il modello</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="build.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase
>Creare il modello</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>

  <para
>Con l'utilizzo di questo output dettagliato è molto più facile trovare problemi con i dati di input.</para>
</sect1>

<sect1 id="test">
  <title
>Test del modello</title>
  <para
>Qui è possibile testare il modello vocale.</para>
  <para
>&kmyapplication; eseguirà il test del modello impostato nella sezione <guilabel
>file di output</guilabel
> della <link linkend="input_output"
>sezione entrata &amp; uscita</link
>.</para>

  <para
>During testing, the recognizer of the selected backend will run to recognize on the input files as set by the test prompts. Resulting word- and sentence errors will be counted as well as the overall robustness by analyzing confidence scores of the recognizer.</para>

  <para
>The main test screen will show all started tests and report when they complete. The tests themselves will run threaded (at the same time). The amount of parallelism best suited for your machine is determined automatically.</para>

<para>
<screenshot>
<screeninfo
>Test del modello</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="test_model.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase
>Test del modello</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>

<para
>As soon as all tests are finished, the <link linkend="test_results"
>test results</link
> will be displayed automatically.</para>


</sect1>

<sect1 id="test_results">
  <title
>Risultati del test</title>

  <para
>Dopo un test di successo <link linkend="test"
>del modello</link
> è possibile trovare un resoconto dettagliato della precisione del riconoscimento qui.</para>

  <sect2 id="scoring">
    <title
>Punteggio</title>

    <para
>Per riflettere le migliori prestazioni di riconoscimento, &kmyapplication;, utilizza più risultati classificati per le prove.</para>

    <para
>A correctly recognized word or sentence will be scored with the confidence score the word achieved. If a word is recognized correctly but another, wrong, result is ranked higher, the accuracy of that recognition will be 0%.</para>

    <para
>The displayed overall recognition rate is the average of all confidence rates. The shown overall accuracy rating shows the average over all accuracy scores which represents the likelihood that given any word in any sentence, this word has been recognized correctly.</para>

  </sect2>

  <sect2 id="test_results_words">
    <title
>Parola</title>

    <para
>&kmyapplication; elencherà la precisione di riconoscimento per ogni singola parola.</para>

    <para>
    <screenshot>
    <screeninfo
>Risultati per la parola</screeninfo>
      <mediaobject>
        <imageobject>
          <imagedata fileref="test_result_words.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase
>Risultati per la parola</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
    </para>

    <para
>If you have samples containing more than one word they will be segmented during recognition. Each word will be scored individually (although the different words of course still influence each other).</para>
  </sect2>

  <sect2 id="test_results_sentences">
    <title
>Frasi</title>
    <para
>Questa sezione elenca ogni richiesta come «frase».</para>

    <para
>Le richieste che sono state registrate più di una volta vengono combinate.</para>

    <para>
    <screenshot>
    <screeninfo
>Risultati per la frase</screeninfo>
      <mediaobject>
        <imageobject>
          <imagedata fileref="test_result_sentences.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase
>Risultati per la frase</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
    </para>
  </sect2>

  <sect2 id="test_results_files">
    <title
>File</title>
    <para
>Nella sezione file è possibile vedere i risultati del riconoscimento per ogni file. Ogni file elencherà <link linkend="scoring"
>i 10 risultati più attinenti</link
> nel pannello dei dettagli al momento della selezione.</para>

    <para>
    <screenshot>
    <screeninfo
>Risultati per i file</screeninfo>
      <mediaobject>
        <imageobject>
          <imagedata fileref="test_result_files.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase
>Risultati per i file</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
    </para>

    <para
>Quando trovi campioni problematici, è possibile ri-registrarli (o rimuoverli) selezionandoli e facendo clic su <guibutton
>Modifica campione</guibutton
>.</para>

    <para
>È possibile ordinare i file per ogni colonna semplicemente cliccando sull'intestazione della colonna. In questo modo è molto facile trovare cattivi campioni ordinando per velocità di riconoscimento.</para>
  </sect2>

  <sect2 id="test_results_log">
    <title
>Log</title>
    <para
>Here you can review the full protocol of this subtest.</para>

    <para>
    <screenshot>
    <screeninfo
>Test log</screeninfo>
      <mediaobject>
        <imageobject>
          <imagedata fileref="test_result_log.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase
>Test log</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
    </para>
  </sect2>
</sect1>



<sect1 id="reports">
  <title
>Reports</title>

  <para
>&kmyapplication; can export reports about test results.</para>

  <para
>The export of a report can be started by selecting <guibutton
>Export test result</guibutton
> in the &kmyapplication; main window.</para>

  <sect2 id="templates">
    <title
>Templates</title>
    <para
>Reports are created by filling in templates with information. Principally, these templates are either plain text files or LaTeX files.</para>

    <para
>Three templates of LaTeX templates, two German and one English one, are shipped with &kmyapplication; but adding new ones is easy. Just install new templates to one of the following locations depending on your operating system: <itemizedlist>
      <listitem
><para
>Linux: <filename
>~/.kde/share/apps/sam/reports/templates</filename
></para
></listitem>
      <listitem
><para
>Windows: <filename
>%appdata%\.kde\share\apps\sam\reports\templates</filename
></para
></listitem>
    </itemizedlist>
    </para>

    <para
>The existing templates can be used as references. They are to be found at the following path: <itemizedlist>
      <listitem
><para
>Linux: <filename
>/usr/share/apps/sam/reports/templates</filename
></para
></listitem>
      <listitem
><para
>Windows: <filename
>&lt;installation path&gt;\share\apps\sam\reports\templates</filename
></para
></listitem>
    </itemizedlist>
    </para>
  </sect2>


  <sect2 id="parameters">
    <title
>Providing meta-information</title>

    <para
>The reporting engine allows the input of meta information about the used input data as well as the test conditions, speakers, etc.</para>

    <para>
    <screenshot>
    <screeninfo
>Report: General information</screeninfo>
      <mediaobject>
        <imageobject>
          <imagedata fileref="test_result_export_main.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase
>Report: General information</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
    </para>

    <para
>This information can be entered directly through the graphical user interface. Depending on the used template, not all provided information might be used by the exported report.</para>

    <para>
    <screenshot>
    <screeninfo
>Report: Experiment information</screeninfo>
      <mediaobject>
        <imageobject>
          <imagedata fileref="test_result_export_experiment.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase
>Report: Experiment information</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
    </para>

    <para
>Information entered in the dialog will also be saved with your &kmyapplication; project file.</para>


    <para>
    <screenshot>
    <screeninfo
>Report: Test set</screeninfo>
      <mediaobject>
        <imageobject>
          <imagedata fileref="test_result_export_testset.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase
>Report: Test setinformation</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
    </para>

    <para
>Some meta information, like the amount of samples in your test- and training corpus and the system information can be either filled in by &kmyapplication; automatically or provided manually.</para>

  </sect2>

  <sect2 id="output">
    <title
>Output</title>

    <para
>Exported reports are stored as ZIP archives. In the case of LaTeX templates they may contain graphics in addition to the raw <filename
>.tex</filename
> file.</para>

    <para
>Below you can see the beginning of an exported full LaTeX report of a simple test of the Amarok scenario with the static Voxforge base model.</para>

    <para>
    <screenshot>
    <screeninfo
>Exported report</screeninfo>
      <mediaobject>
        <imageobject>
          <imagedata fileref="test_result_export_pdf.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase
>Exported report</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
    </para>
  </sect2>
</sect1>




<sect1 id="command_line_args">
  <title
>Command line arguments</title>

  <para
>&kmyapplication; provides command line arguments for the most common actions to automatize model creation and testing.</para>

  <para
>All actions provided as command line arguments will be taken immediately after &kmyapplication; has loaded. Options that build on one another (like compiling and testing) will be re-ordered automatically.</para>

<table frame='all'
><title
>Command line arguments</title>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
  <entry
>Argument</entry>
  <entry
>Description</entry>
</row>
</thead>
<tbody>
<row>
  <entry
><parameter
>-m &lt;type&gt;</parameter
></entry>
  <entry
>Selects the used backend; Provide either "sphinx" or "htk" to select the specified backend. Depending on your installation, "sphinx" might not be available.</entry>
</row>
<row>
  <entry
><parameter
>-s</parameter
></entry>
  <entry
>Retrieves all paths from Simon; (equivalent to <guibutton
>Modify Simon's model</guibutton
>)</entry>
</row>
<row>
  <entry
><parameter
>-c</parameter
></entry>
  <entry
>Starts the model compilation;</entry>
</row>
<row>
  <entry
><parameter
>-t</parameter
></entry>
  <entry
>Starts the model test;</entry>
</row>
<row>
  <entry
><parameter
>-e &lt;filename&gt;</parameter
></entry>
  <entry
>Exports a report to the given filename;</entry>
</row>
<row>
  <entry
><parameter
>-b</parameter
></entry>
  <entry
>Enables batch processing; &kmyapplication; will quit automatically after all arguments have been processed. The main window will not be shown.</entry>
</row>
<row>
  <entry
><parameter
>-l &lt;filename&gt;</parameter
></entry>
  <entry
>Export the complete build log to the given file;</entry>
</row>
<row>
  <entry
><parameter
>-w</parameter
></entry>
  <entry
>Automatically safe any opened &kmyapplication; project file when exiting the application;</entry>
</row>
<row>
  <entry
><parameter
>&lt;filename&gt;</parameter
></entry>
  <entry
>Load this &kmyapplication; project file during startup.</entry>
</row>
</tbody>
</tgroup>
</table>

</sect1>

</chapter>


<chapter id="faq">
<title
>Domande e risposte</title>

<para
>In an effort to keep this section always up-to-date it is available at our <ulink url="http://userbase.kde.org/Special:myLanguage/Simon/Troubleshooting_Guide"
>online wiki</ulink
>. </para>

</chapter>

<chapter id="credits">
<title
>Riconoscimenti e licenza</title>

<para
>&kmyapplication; </para>
<para
>Program copyright 2008-2010 Peter Grasch <email
>peter.grasch@bedahr.org</email
> </para>

<para
>Documentation Copyright &copy; 2009-2010 Peter Grasch <email
>peter.grasch@bedahr.org</email
> </para>

<para
>Innocenzo Ventre<email
>innocenzo.ventre@gmail.com</email
></para
> 
&underFDL; &underGPL; </chapter>

<appendix id="installation">
<title
>Installazione</title>
<para
>Please see our <ulink url="http://userbase.kde.org/Special:myLanguage/Simon/Installation"
>wiki</ulink
> for installation instructions.</para>
</appendix>

&documentation.index;
</book>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab
kate: space-indent on; indent-width 2; tab-width 2; indent-mode none;
-->
