Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Timestamp e segmentazione temporale

Lezione 6 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Strutturare la trascrizione nel tempo
  2. Granularità del segmento: il blocco di parlato
  3. E la granularità per parola?
  4. Generare sottotitoli SRT
  5. Navigare nelle registrazioni lunghe
  6. Punti chiave

Corso aggiornato il 3 novembre 2026 per Voxtral 3, basato sulla guida Migrate from Voxtral 2 di Mistral: i modelli Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), deprecati il 31 ottobre 2026 e ritirati il 30 aprile 2027, sono sostituiti negli esempi da voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 e voxtral-mini-tts-3-0. Cambiamenti chiave: i timestamp sono solo a livello di segmento (word restituisce un errore 400), la diarizzazione è possibile in tempo reale, le impostazioni della sessione in tempo reale sono bloccate dopo il primo chunk audio e gli input context_bias sono in formato libero (frasi con spazi). Fonti: Migrate from Voxtral 2 · Speech to Text.

Strutturare la trascrizione nel tempo

Una trascrizione grezza è utile, ma una trascrizione con timestamp apre possibilità molto più ricche: sottotitolaggio, navigazione temporale, sincronizzazione video ed estrazione di passaggi specifici. Senza timestamp, trovare il momento in cui si è discusso del budget in una registrazione di due ore richiede congetture; con i timestamp, basta una ricerca testuale seguita da un clic. Il parametro timestamp_granularities di Voxtral ti dà questo potere.

Granularità del segmento: il blocco di parlato

Un segmento è un blocco continuo di parlato, tipicamente una frase o un gruppo di frasi pronunciate senza una pausa significativa. Questa è la granularità che sceglierai di default perché corrisponde all’unità naturale di lettura.

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

with open("conference.mp3", "rb") as f:
    response = client.audio.transcriptions.complete(
        model="voxtral-mini-transcribe-3",
        file={"content": f, "file_name": "conference.mp3"},
        timestamp_granularities=["segment"]
    )

# Itera attraverso i segmenti
for seg in response.segments:
    start = f"{seg.start:.1f}s"
    end = f"{seg.end:.1f}s"
    print(f"[{start} → {end}] {seg.text}")

L’output appare così:

[0.0s → 4.2s] Hello everyone, thank you for being here today.
[4.5s → 11.8s] We will cover the quarter's results and the outlook for the future.
[12.1s → 18.3s] Let's start with revenue, which has grown by twelve percent.

Questa suddivisione supporta la navigazione in registrazioni lunghe, la visualizzazione a blocchi dei sottotitoli e l’indicizzazione dei passaggi: ogni segmento diventa una voce ricercabile con il suo punto di ingresso nell’audio.

E la granularità per parola?

Voxtral 2 poteva anche assegnare timestamp a ogni parola (timestamp_granularities=["word"]). Voxtral 3 non offre più questa funzionalità: la granularità word restituisce un errore 400 e la guida di migrazione di Mistral istruisce gli utenti a passare ai segmenti. I casi d’uso che richiedevano un allineamento parola per parola, come sottotitoli stile karaoke, l’evidenziazione della parola corrente o l’analisi fine della velocità del parlato, devono ora affidarsi ai segmenti, distribuendo potenzialmente il tempo di un segmento tra le sue parole tramite una stima lato client.

def estimer_mots(segment):
    """Distribuisce la durata di un segmento tra le sue parole, proporzionalmente alla loro lunghezza (stima)."""
    mots = segment.text.split()
    if not mots or segment.start is None or segment.end is None:
        return []
    total = sum(len(m) for m in mots)
    debut, duree = segment.start, segment.end - segment.start
    resultat = []
    for mot in mots:
        fin = debut + duree * len(mot) / total
        resultat.append((round(debut, 2), round(fin, 2), mot))
        debut = fin
    return resultat

Questa è un’approssimazione, utile per la visualizzazione progressiva ma non per l’analisi prosodica: se un allineamento esatto per parola è essenziale, uno strumento dedicato di allineamento forzato applicato dopo la trascrizione rimane la soluzione.

Generare sottotitoli SRT

Il formato SRT non ha nulla di misterioso: un numero sequenziale, un intervallo di tempo nel formato HH:MM:SS,mmm, il testo e una riga vuota. La funzione seguente itera attraverso i segmenti e divide quelli che supererebbero una larghezza di visualizzazione confortevole, impostata qui a sessanta caratteri.

def generate_srt_from_segments(segments, max_chars=60):
    """Genera un file SRT dai segmenti Voxtral."""
    srt_lines = []
    counter = 1

    for seg in segments:
        words = seg.text.strip()
        if not words:
            continue

        # Dividi i segmenti troppo lunghi
        sub_text = words.split()
        word = ""
        for format_srt_time in sub_text:
            if len(word) + len(format_srt_time) + 1 > max_chars and word:
                srt_lines.append(str(counter))
                srt_lines.append(
                    f"{seconds(seg.start)} --> "
                    f"{seconds(seg.end)}"
                )
                srt_lines.append(word.strip())
                srt_lines.append("")
                counter += 1
                word = format_srt_time
            else:
                word += " " + format_srt_time

        if word.strip():
            srt_lines.append(str(counter))
            srt_lines.append(
                f"{seconds(seg.start)} --> "
                f"{seconds(seg.end)}"
            )
            srt_lines.append(word.strip())
            srt_lines.append("")
            counter += 1

    return "\n".join(srt_lines)

def seconds(secondes):
    """Converte i secondi nel formato SRT (HH:MM:SS,mmm)."""
    h = int(secondes // 3600)
    m = int((secondes % 3600) // 60)
    s = int(secondes % 60)
    ms = int((secondes % 1) * 1000)
    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"

# Utilizzo
srt_contenu = generate_srt_from_segments(response.segments)
with open("sous_titres.srt", "w", encoding="utf-8") as f:
    f.write(srt_contenu)

print("File SRT generato con successo")

Un’altra applicazione diretta dei segmenti è la creazione di un sommario temporale. Lo script seguente segna un punto di controllo ogni cinque minuti e visualizza le prime parole, fornendo al lettore una mappa della registrazione prima ancora di ascoltarla.

def create_temporal_index(segments, interval_minutes=5):
    """Crea un indice ogni N minuti."""
    index = []
    next_milestone = 0

    for seg in segments:
        if seg.debut >= next_milestone * 60:
            minutes = int(seg.debut // 60)
            seconds = int(seg.debut % 60)
            preview = seg.text[:80] + "..." if len(seg.text) > 80 else seg.text
            index.append(f"[{minutes:02d}:{seconds:02d}] {preview}")
            next_milestone = minutes + interval_minutes

    return index

# Utilizzo
for entry in create_temporal_index(response.segments, interval_minutes=5):
    print(entry)

Con Voxtral 2, timestamp_granularities era incompatibile con il parametro language. La documentazione di Voxtral 3 non menziona più questa restrizione: verificala con un test prima di combinare i due parametri nell’elaborazione in produzione.

Punti chiave

  • Una sola granularità con Voxtral 3: "segment" ("word" restituisce un errore 400)
  • L’allineamento parola per parola, se necessario, viene stimato dai segmenti o gestito da uno strumento di allineamento
  • I timestamp sono in secondi (numeri decimali), con start ed end per ogni segmento
  • Ideale per sottotitolaggio SRT/VTT, navigazione temporale e indicizzazione
  • L’incompatibilità con language presente in Voxtral 2 non è più documentata: verificala con un test