Come ottenere il timestamp di ogni parola da una registrazione

La richiesta

{
  "audio_url": "https://example.com/interview.mp3",
  "model": "oracle",
  "language": "auto",
  "word_timestamps": true,
  "output_format": "json"
}

Avvia la trascrizione con POST /transcribe e interroga GET /transcribe/{jobId} finché lo stato non passa a COMPLETED. Specifica sempre il parametro model, altrimenti l’API userà di default il vecchio modello core.

La risposta

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 1.0,
        "end": 3.75,
        "text": "Hello everyone and welcome to the show.",
        "speaker": "Speaker 1",
        "words": [
          { "start": 1.0, "end": 1.35, "word": "Hello" },
          { "start": 1.4, "end": 1.75, "word": "everyone" }
        ]
      }
    ]
  }
}

• segments[]: contiene start ed end in secondi, text, speaker (se la diarizzazione è attiva) e l’array words[].
• words[]: contiene start, end e word, con i tempi in secondi arrotondati al terzo decimale.
• Una parola molto breve può durare pochi centesimi di secondo, o persino avere lo stesso valore per start ed end. Evita quindi nel codice di dividere per la durata di una parola.
• Se imposti word_timestamps su false, oppure usi un modello che calcola i tempi solo per intero segmento, il campo words non sarà presente e avrai solo start ed end a livello di segmento.

Quali modelli restituiscono i tempi per parola

Il testo (txt) non ha tempi. L’SRT costruito dall’API segue lo stesso interruttore; vedi la guida all’SRT.

Trovare il punto esatto in cui viene detta una frase

Se unisci tutte le parole in un unico elenco, puoi cercare un testo e ricavarne l’intervallo di tempo. È così che un agente può rispondere a «dove cita i prezzi?» indicando il momento esatto, o ritagliare quella frase per farne una clip.

find.py

# find.py — where is a phrase said? Returns (start, end) in seconds.
import re


def find_phrase(result, phrase):
    words = [w for segment in result["segments"] for w in segment.get("words", [])]
    clean = lambda text: re.sub(r"[^\w]", "", text.lower())
    target = [clean(p) for p in phrase.split()]
    tokens = [clean(w["word"]) for w in words]
    for i in range(len(tokens) - len(target) + 1):
        if tokens[i:i + len(target)] == target:
            return words[i]["start"], words[i + len(target) - 1]["end"]
    return None


# start, end = find_phrase(result, "welcome to the show")
# ffmpeg -ss <start> -to <end> -i talk.mp4 -c:v libx264 -c:a aac clip.mp4

Estrarre un clip a partire da un intervallo di tempo:

ffmpeg -ss 41.2 -to 47.8 -i talk.mp4 -c:v libx264 -c:a aac clip.mp4

Accorciare le pause e creare jump cut

Conoscendo inizio e fine di ogni parola puoi calcolare la durata delle pause. Mantieni il parlato continuo e taglia i silenzi che superano una certa soglia:

silences.py

# silences.py — keep the speech, drop pauses longer than max_gap seconds
def speech_ranges(words, max_gap=0.7, pad=0.1):
    ranges = []
    for word in words:
        if ranges and word["start"] - ranges[-1][1] <= max_gap:
            ranges[-1][1] = word["end"]
        else:
            ranges.append([word["start"], word["end"]])
    return [[max(0.0, s - pad), e + pad] for s, e in ranges]

# Pass the ranges to cut() from cut.py to build the tightened video.

Poi unisci gli intervalli usando la funzione cut() mostrata nella guida al montaggio video.

Altri modi per usare i timestamp

• Testo sincronizzato in un player web: evidenzia via via la parola il cui intervallo contiene il valore currentTime del player.
• Trascrizioni interattive: trasforma ogni parola in un link che punta a ?t=<start> per far saltare il player a quel punto.
• Capitoli e momenti chiave: fai scegliere a un LLM i numeri dei segmenti più rilevanti e usa il tuo codice per convertirli in timestamp.
• Ricerca in un archivio: salva nel database le parole insieme al loro tempo di inizio, così chi cerca un termine può aprire il file direttamente al secondo esatto.
• Allineamento e lavoro sui corpora: puoi convertire i tempi delle parole dal JSON nei formati di annotazione che i tuoi strumenti sanno leggere.

Quanto costa

I timestamp per parola non comportano costi aggiuntivi. Paghi solo i secondi di audio elaborati in base al modello scelto, a partire da 0,48 US$ all’ora con base (un’ora con oracle costa 1,44 US$). Trovi il listino completo in /llms/pricing.md.

Domande e risposte