Annotation audio

Configurez l'annotation audio sur forme d'onde dans Potato. Affichez des contrôles de lecture interactifs, posez des repères temporels et combinez avec des schémas radio, likert ou texte.

Potato 2.0 prend en charge l'annotation audio avec visualisation de la forme d'onde par Peaks.js, étiquetage de segments et raccourcis clavier.

Cas d'usage

Transcription et relecture de parole
Diarisation des locuteurs
Analyse musicale
Détection d'événements sonores
Reconnaissance des émotions dans la parole
Contrôle qualité des centres d'appels

Activer le support audio

Ajoutez une section audio_annotation à votre configuration :

yaml

annotation_schemes:
  - annotation_type: audio_annotation
    name: audio_segments
    description: "Segment and label the audio"
    labels:
      - Speech
      - Music
      - Silence
      - Noise

Modes de fonctionnement

Potato propose trois modes d'annotation audio :

Mode étiquetage

Découper l'audio en segments et attribuer une catégorie à chacun :

yaml

annotation_schemes:
  - annotation_type: audio_annotation
    name: speaker_diarization
    mode: label
    description: "Identify speakers in the audio"
    labels:
      - Speaker A
      - Speaker B
      - Overlap

Mode questions

Poser des questions d'annotation segment par segment :

yaml

annotation_schemes:
  - annotation_type: audio_annotation
    name: speech_quality
    mode: questions
    description: "Evaluate speech segments"
    segment_schemes:
      - annotation_type: radio
        name: speaker_type
        description: "Who is speaking?"
        labels: ["host", "guest", "unknown"]
      - annotation_type: likert
        name: clarity
        description: "How clear is this segment?"
        size: 5
        min_label: "Unintelligible"
        max_label: "Perfectly clear"

Mode combiné

Associer l'étiquetage et les questions par segment :

yaml

annotation_schemes:
  - annotation_type: audio_annotation
    name: full_analysis
    mode: both
    description: "Label and analyze audio segments"
    labels:
      - Speech
      - Music
      - Noise
    segment_schemes:
      - annotation_type: radio
        name: foreground
        description: "Is this the foreground audio?"
        labels: ["Yes", "No"]

Options de configuration

Configuration de base

yaml

annotation_schemes:
  - annotation_type: audio_annotation
    name: segments
    description: "Create audio segments"
    labels:
      - Label A
      - Label B
 
    # Optional constraints
    min_segments: 1
    max_segments: 50

Raccourcis clavier

Les étiquettes s'attribuent avec les touches numériques 1 à 9 :

yaml

annotation_schemes:
  - annotation_type: audio_annotation
    name: speakers
    description: "Mark each speaker turn"
    labels:
      - Speaker A  # Press 1
      - Speaker B  # Press 2
      - Overlap    # Press 3

Couleurs des étiquettes

Personnalisez la couleur des segments :

yaml

annotation_schemes:
  - annotation_type: audio_annotation
    name: segments
    description: "Segment the recording and label each region"
    labels:
      - name: Speech
        color: "#22C55E"
      - name: Music
        color: "#3B82F6"
      - name: Silence
        color: "#9CA3AF"

Performance de la forme d'onde

Pour de bonnes performances sur les fichiers audio longs, installez l'outil audiowaveform de la BBC :

bash

# macOS
brew install audiowaveform
 
# Ubuntu/Debian
sudo apt-get install audiowaveform
 
# Or build from source
# https://github.com/bbc/audiowaveform

La forme d'onde est alors générée côté serveur. Sans cet outil, la génération se fait côté client, ce qui convient aux fichiers de moins de 30 minutes.

Mise en cache des formes d'onde

Réglez la mise en cache pour gagner en réactivité :

yaml

audio_annotation:
  waveform_cache_dir: waveform_cache/     # Where pre-computed waveforms are stored
  waveform_look_ahead: 3                  # Pre-compute the next N instances
  waveform_cache_max_size: 50             # Maximum cached waveform files
  client_fallback_max_duration: 1800      # Longest file the browser will render, in seconds

Format des données

Référence audio simple

json

[
  {"id": "1", "audio_path": "audio/recording_001.wav"},
  {"id": "2", "audio_path": "audio/recording_002.wav"}
]

yaml

data_files:
  - "data/audio_data.json"
 
item_properties:
  id_key: id
  text_key: audio_path   # The field holding the audio URL

Avec transcriptions

json

[
  {
    "id": "1",
    "audio_path": "audio/call_001.wav",
    "transcript": "Hello, how can I help you today?"
  }
]

Une chaîne de texte simple comme celle-ci affiche la transcription à côté de la forme d'onde, à titre de contexte. Si votre transcription contient des timings, qu'elle vienne de Whisper, d'une API ASR cloud ou d'un fichier de sous-titres, passez plutôt le fichier lui-même : Potato affichera les tours de parole sous forme de bulles synchronisées avec l'audio.

json

[
  {
    "id": "1",
    "conversation": {"audio": "audio/call_001.wav",
                     "transcript": "audio/call_001.srt"}
  }
]

21 formats de transcription et de sous-titres sont reconnus d'après leur contenu et non leur extension. Voir Formats de transcription.

Format de sortie

Les annotations sont enregistrées avec les horodatages des segments :

json

{
  "id": "audio_1",
  "annotations": {
    "segments": [
      {
        "start": 0.0,
        "end": 2.5,
        "label": "Speaker A",
        "questions": {
          "clarity": 4,
          "emotion": "Neutral"
        }
      },
      {
        "start": 2.5,
        "end": 5.2,
        "label": "Speaker B"
      }
    ]
  }
}

Raccourcis clavier

Potato fournit des raccourcis clavier pour annoter efficacement :

Raccourci	Action
`Space`	Lecture / pause
`[`	Placer le début du segment à la position courante
`]`	Placer la fin du segment à la position courante
`1-9`	Attribuer une étiquette au segment courant
`Delete`	Supprimer le segment courant
`Left Arrow`	Reculer de 5 secondes
`Right Arrow`	Avancer de 5 secondes
`Up Arrow`	Zoom avant
`Down Arrow`	Zoom arrière
`Home`	Aller au début
`End`	Aller à la fin
`+`	Accélérer la lecture
`-`	Ralentir la lecture

Exemples de configuration

Diarisation des locuteurs

yaml

annotation_task_name: "Speaker Diarization"
task_dir: "."
port: 8000
 
data_files:
  - "data/recordings.json"
 
item_properties:
  id_key: id
  text_key: audio_path
 
annotation_schemes:
  - annotation_type: audio_annotation
    name: speakers
    mode: label
    description: "Identify who is speaking"
    labels:
      - Speaker 1
      - Speaker 2
      - Speaker 3
      - Overlap
      - Silence
    min_segments: 1
 
# Diarization recordings run long, so precompute a few ahead of the annotator.
audio_annotation:
  waveform_cache_dir: waveform_cache/
  waveform_look_ahead: 5
 
output_annotation_dir: "output/"
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true

Relecture de transcription

yaml

annotation_task_name: "Transcription Quality Review"
task_dir: "."
port: 8000
 
data_files:
  - "data/transcripts.json"
 
item_properties:
  id_key: id
  text_key: audio_path
 
annotation_schemes:
  - annotation_type: audio_annotation
    name: errors
    mode: questions
    description: "Mark transcription errors"
    # Questions mode collects answers per marked region, so the error type and
    # the correction stay attached to the stretch of audio they describe.
    segment_schemes:
      - annotation_type: radio
        name: error_type
        description: "What kind of error is this?"
        labels: ["Substitution", "Deletion", "Insertion", "Speaker mix-up"]
      - annotation_type: text
        name: correction
        description: "What should the transcript say?"
 
  - annotation_type: radio
    name: overall_accuracy
    description: "Overall transcript accuracy"
    labels:
      - Accurate
      - Minor errors
      - Major errors
      - Unusable
 
output_annotation_dir: "output/"
export_annotation_format: jsonl

Cette configuration fait relire la transcription segment par segment en regard de la forme d'onde. Quand la transcription sort d'une chaîne ASR et porte déjà des timings, le schéma speech_transcript convient mieux : il lit directement Whisper, Deepgram, AssemblyAI, SRT, WebVTT et 16 autres formats, et présente aux annotateurs des cartes de segment avec étiquettes d'erreur et champ de correction. Voir Formats de transcription et Annoter des transcriptions Whisper.

Contrôle qualité en centre d'appels

yaml

annotation_task_name: "Call Center Quality Assurance"
task_dir: "."
port: 8000
 
data_files:
  - "data/calls.json"
 
item_properties:
  id_key: call_id
  text_key: recording_path
 
annotation_schemes:
  # Segment-level annotation
  - annotation_type: audio_annotation
    name: conversation
    mode: both
    description: "Segment the conversation"
    labels:
      - Agent
      - Customer
      - Hold
      - Silence
    # Who is speaking is a label; how the turn went is a question about it.
    segment_schemes:
      - annotation_type: radio
        name: tone
        description: "Tone of this turn"
        labels: ["Calm", "Neutral", "Escalated"]
 
  # Call-level assessment
  - annotation_type: likert
    name: professionalism
    description: "Agent professionalism"
    size: 5
    min_label: "Poor"
    max_label: "Excellent"
 
  - annotation_type: likert
    name: resolution
    description: "Issue resolution"
    size: 5
    min_label: "Unresolved"
    max_label: "Fully resolved"
 
  - annotation_type: multiselect
    name: issues
    description: "Select any issues observed"
    labels:
      - Long hold time
      - Agent interrupted
      - Incorrect information
      - Missing greeting
      - Unprofessional language
 
  - annotation_type: text
    name: notes
    description: "Additional observations"
    rows: 4
 
output_annotation_dir: "output/"
export_annotation_format: jsonl

Formats audio pris en charge

WAV (recommandé pour la qualité)
MP3
OGG
FLAC
M4A
WebM

Conseils de performance

Installez audiowaveform - Indispensable pour les fichiers audio longs
Activez le cache - Utilisez cache_dir pour conserver les formes d'onde déjà générées
Préférez le WAV - Les formats compressés peuvent introduire des artefacts
Prétraitez l'audio - Normalisez les niveaux, coupez les silences inutiles
Surveillez la taille des fichiers - Les gros fichiers ralentissent le chargement
Utilisez la précompilation - Générez à l'avance les formes d'onde des premières instances

Dépannage

La forme d'onde ne se charge pas

Vérifiez le chemin du fichier audio
Vérifiez que le format est pris en charge
Installez audiowaveform pour les fichiers longs
Regardez la console du navigateur

Lenteurs

Installez l'outil audiowaveform
Activez la mise en cache des formes d'onde
Réduisez la taille des fichiers audio
Utilisez le réglage precompute_depth

Les segments ne sont pas enregistrés

Vérifiez que le répertoire de sortie est accessible en écriture
Vérifiez la configuration du format d'annotation
Vérifiez que le segment a bien une heure de début et une heure de fin