.. note::

    Ciao, benvenuto nella Community SunFounder Raspberry Pi & Arduino & ESP32 su Facebook! Esplora a fondo Raspberry Pi, Arduino ed ESP32 insieme ad altri appassionati.

    **Perché unirti a noi?**

    - **Supporto esperto**: Risolvi problemi post-vendita e sfide tecniche con l'aiuto della nostra community e del nostro team.
    - **Impara e condividi**: Scambia suggerimenti e tutorial per migliorare le tue competenze.
    - **Anteprime esclusive**: Accedi in anteprima agli annunci di nuovi prodotti.
    - **Sconti speciali**: Approfitta di sconti esclusivi sui nostri prodotti più recenti.
    - **Promozioni festive e giveaway**: Partecipa a concorsi e promozioni speciali.

    👉 Sei pronto a esplorare e creare con noi? Clicca [|link_sf_facebook|] e unisciti subito!

.. _py_stt:

15. STT (Speech-to-Text)
==============================================

Questo esempio mostra come utilizzare il modulo STT (Speech-to-Text) su
PiCrawler. Il robot ascolta la tua voce attraverso il microfono integrato
e la converte in testo in tempo reale.

**Esegui il codice**

.. raw:: html

    <run></run>

.. code-block::

    cd ~/picrawler/examples
    sudo python3 15_stt.py

Dopo aver eseguito il programma, vedrai l'impostazione della lingua e un
prompt. Il robot inizia ad ascoltare — parla nel microfono e il testo
riconosciuto verrà stampato nel terminale.

Se non viene rilevata alcuna voce, viene mostrato ``(no speech detected)``.
Premi **Ctrl+C** per uscire.

**Prima di iniziare**

Assicurati di aver completato:

* :ref:`install_all_modules` — Installa i moduli ``robot-hat``, ``vilib``,
  ``picrawler``, quindi esegui lo script ``i2samp.sh``.

**Codice**

.. note::
    Puoi **Modificare/Reimpostare/Copiare/Eseguire/Fermare** il codice qui
    sotto. Ma prima, devi andare nel percorso del codice sorgente come
    ``picrawler\examples``. Dopo aver modificato il codice, puoi eseguirlo
    direttamente per vedere l'effetto.

.. raw:: html

    <run></run>

.. code-block:: python

    #!/usr/bin/env python3
    from robot_hat.stt import STT

    # Demo di riconoscimento vocale con il modulo STT di sunfounder_voice_assistant
    # Ctrl+C per uscire

    # Configura lingua: "en-us", "zh-cn", "it-it", ecc.
    LANGUAGE = "en-us"

    def main():
        print("=== Demo PiCrawler Speech-to-Text ===")
        print(f"Lingua: {LANGUAGE}")
        print("Ctrl+C per uscire")
        print()

        stt = STT(language=LANGUAGE)

        try:
            while True:
                print("In ascolto... (parla ora)")
                text = stt.listen()
                if text:
                    print(f">>> {text}")
                else:
                    print("(nessuna voce rilevata)")
        except KeyboardInterrupt:
            print("\nUscita...")

    if __name__ == "__main__":
        main()


**Come funziona?**

#. Importazione del modulo STT

   .. code-block:: python

      from robot_hat.stt import STT

   La classe ``STT`` fa parte del pacchetto ``robot_hat``. Gestisce tutta la
   cattura audio di basso livello e l'elaborazione del riconoscimento vocale.

#. Impostazione della lingua

   .. code-block:: python

      LANGUAGE = "en-us"

   La variabile ``LANGUAGE`` configura la lingua di riconoscimento. Puoi
   cambiarla con altri codici supportati come ``"zh-cn"`` (cinese) o
   ``"it-it"`` (italiano) in base alle tue esigenze.

#. Creazione dell'istanza STT

   .. code-block:: python

      stt = STT(language=LANGUAGE)

   Questo crea un oggetto STT configurato per la lingua scelta. L'oggetto
   inizializza il microfono e il motore di riconoscimento vocale.

#. Il ciclo di ascolto

   .. code-block:: python

      while True:
          print("In ascolto... (parla ora)")
          text = stt.listen()
          if text:
              print(f">>> {text}")
          else:
              print("(nessuna voce rilevata)")

   Il programma esegue un ciclo infinito dove ogni iterazione:

   - Invita l'utente a parlare.
   - Chiama ``stt.listen()`` che si blocca finché la voce non viene rilevata
     ed elaborata.
   - Restituisce il testo riconosciuto come stringa, o ``None`` / vuoto se
     non è stato compreso nulla.
   - Stampa il risultato nel terminale.

#. Uscita controllata

   .. code-block:: python

      except KeyboardInterrupt:
          print("\nUscita...")

   Premere **Ctrl+C** genera un ``KeyboardInterrupt``, che viene catturato per
   stampare un messaggio di uscita e terminare il programma in modo pulito.