secondvoice/docs/next_steps.md

SecondVoice - Prochaines Étapes

Date: 20 novembre 2025 Status: Setup complet, ready to build

---

✅ Ce qui est fait

Infrastructure

• ✅ Structure projet complète (src/, docs/, recordings/)
• ✅ CMakeLists.txt configuré avec vcpkg
• ✅ vcpkg.json avec toutes les dépendances
• ✅ .gitignore configuré
• ✅ config.json template
• ✅ .env.example
• ✅ build.sh helper script
• ✅ README.md complet

Code Implémenté

• ✅ audio/AudioCapture: PortAudio wrapper pour capture audio
• ✅ audio/AudioBuffer: Buffer avec export WAV
• ✅ api/WhisperClient: Client HTTP pour Whisper API (multipart/form-data)
• ✅ api/ClaudeClient: Client HTTP pour Claude API (JSON)
• ✅ ui/TranslationUI: Interface ImGui avec bouton Stop
• ✅ core/Pipeline: Orchestration 3 threads
• ✅ utils/Config: Loader JSON + .env
• ✅ utils/ThreadSafeQueue: Template thread-safe
• ✅ main.cpp: Entry point

Documentation

• ✅ docs/SecondVoice.md (vision projet)
• ✅ docs/implementation_plan.md (design technique)
• ✅ README.md (setup + usage)

---

🚀 Prochaines Actions Immédiates

1. Setup Environnement (Toi)

# 1. Installer vcpkg si pas déjà fait
git clone https://github.com/microsoft/vcpkg.git ~/vcpkg
cd ~/vcpkg
./bootstrap-vcpkg.sh
export VCPKG_ROOT=~/vcpkg
# Ajouter dans ~/.bashrc:
echo 'export VCPKG_ROOT=~/vcpkg' >> ~/.bashrc

# 2. Installer dépendances système
sudo apt update
sudo apt install -y libasound2-dev libgl1-mesa-dev libglu1-mesa-dev

# 3. Créer .env
cd /mnt/e/Users/Alexis\ Trouvé/Documents/Projets/secondvoice
cp .env.example .env
# Éditer .env et ajouter tes vraies API keys:
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
nano .env

2. Premier Build

# Lancer le build
./build.sh

# Ou manuellement:
cmake -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build -j$(nproc)

Note: Le premier build va prendre du temps (vcpkg va compiler toutes les dépendances).

3. Test Audio Simple

Avant de tester le pipeline complet, on va faire un test standalone de l'audio capture.

Créer un test simple (test_audio.cpp):

#include "src/audio/AudioCapture.h"
#include "src/audio/AudioBuffer.h"
#include <iostream>
#include <thread>
#include <chrono>

int main() {
    secondvoice::AudioCapture capture(16000, 1, 5);
    secondvoice::AudioBuffer buffer(16000, 1);

    if (!capture.initialize()) {
        std::cerr << "Failed to init audio" << std::endl;
        return 1;
    }

    std::cout << "Recording 10 seconds..." << std::endl;

    capture.start([&buffer](const std::vector<float>& data) {
        buffer.addSamples(data);
        std::cout << "Captured chunk: " << data.size() << " samples" << std::endl;
    });

    std::this_thread::sleep_for(std::chrono::seconds(10));

    capture.stop();

    if (buffer.saveToWav("test_recording.wav")) {
        std::cout << "Saved to test_recording.wav" << std::endl;
    }

    return 0;
}

Build + test:

# Ajouter test_audio dans CMakeLists.txt (temporaire)
# Ou compiler manuellement

4. Test Whisper API

Créer un test (test_whisper.cpp):

#include "src/api/WhisperClient.h"
#include "src/audio/AudioBuffer.h"
#include <iostream>

int main() {
    // Load API key from .env
    std::string api_key = "sk-...";  // Replace with real key

    secondvoice::WhisperClient client(api_key);

    // Load test audio (Chinese speech)
    secondvoice::AudioBuffer buffer(16000, 1);
    // TODO: Load from existing WAV file

    auto result = client.transcribe(buffer.getSamples(), 16000, 1, "zh", 0.0f);

    if (result.has_value()) {
        std::cout << "Transcription: " << result->text << std::endl;
    } else {
        std::cerr << "Failed" << std::endl;
    }

    return 0;
}

Test avec audio chinois sample:

• Chercher sample audio chinois gratuit (YouTube ou sample sites)
• Convertir en WAV 16kHz mono si nécessaire
• Tester transcription

5. Test Claude API

Créer un test (test_claude.cpp):

#include "src/api/ClaudeClient.h"
#include <iostream>

int main() {
    std::string api_key = "sk-ant-...";  // Replace

    secondvoice::ClaudeClient client(api_key);

    std::string chinese = "你好，今天我们讨论项目进度。";

    auto result = client.translate(chinese);

    if (result.has_value()) {
        std::cout << "Traduction: " << result->text << std::endl;
    } else {
        std::cerr << "Failed" << std::endl;
    }

    return 0;
}

6. Test Pipeline Complet

cd build
./SecondVoice

Ce qui doit se passer:

1. Fenêtre ImGui s'ouvre
2. "Recording..." affiché
3. Audio capturé en temps réel
4. Transcriptions chinoises affichées
5. Traductions françaises affichées
6. Clic "STOP RECORDING" → sauvegarde audio

7. Debug & Fix

Problèmes attendus :

1. Build errors (dépendances vcpkg)

   • Vérifier vcpkg installé
   • Vérifier VCPKG_ROOT
   • Réinstaller package si nécessaire: vcpkg install portaudio

2. Audio capture fails

   • Vérifier microphone disponible: arecord -l
   • Tester avec arecord -d 5 test.wav
   • Vérifier permissions audio

3. Whisper API errors

   • Vérifier clé API
   • Tester avec curl:

     curl https://api.openai.com/v1/audio/transcriptions \
       -H "Authorization: Bearer $OPENAI_API_KEY" \
       -F file=@test.wav \
       -F model=whisper-1
     

4. Claude API errors

   • Vérifier clé API
   • Tester avec curl:

     curl https://api.anthropic.com/v1/messages \
       -H "x-api-key: $ANTHROPIC_API_KEY" \
       -H "anthropic-version: 2023-06-01" \
       -H "content-type: application/json" \
       -d '{
         "model": "claude-haiku-4-20250514",
         "max_tokens": 1024,
         "messages": [{"role": "user", "content": "Traduis: 你好"}]
       }'
     

5. UI doesn't appear

   • Vérifier OpenGL installé: glxinfo | grep OpenGL
   • Tester avec autre ImGui example
   • Vérifier DISPLAY variable si SSH

6. Latence trop élevée

   • Réduire chunk_duration_seconds dans config.json (10s → 5s)
   • Tester avec différentes valeurs
   • Mesurer latence Whisper + Claude séparément

7. Memory leaks

   • Utiliser valgrind: valgrind --leak-check=full ./SecondVoice
   • Vérifier smart pointers utilisés partout

---

🎯 Critères de Succès MVP

Pour valider le MVP, il faut que:

1. ✅ Build compile sans erreurs
2. ✅ Audio capture fonctionne (test avec test_audio)
3. ✅ Whisper transcrit correctement (>85% précision sur sample chinois)
4. ✅ Claude traduit correctement (traduction naturelle FR)
5. ✅ UI s'affiche et reste responsive
6. ✅ Pipeline complet fonctionne bout-à-bout
7. ✅ Bouton Stop arrête proprement et sauvegarde audio
8. ✅ Latence acceptable (<10s entre audio et traduction affichée)
9. ✅ Pas de crash sur 30min recording
10. ✅ Audio sauvegardé est lisible (test avec aplay ou VLC)

---

🔧 Améliorations Possibles (Post-MVP)

Performance

• Optimiser chunk size (benchmark 5s vs 10s vs 30s)
• Pool de threads pour processing parallèle
• Cache API responses (éviter double-call)
• Streaming Whisper (si API supporte)

Qualité

• Retry logic sur API failures (exponential backoff)
• Detect silence (skip chunks vides)
• Audio normalization avant Whisper
• Confidence score Whisper (filter low confidence)

UI/UX

• Settings panel (change chunk size runtime)
• Pause/Resume button
• Volume meter (visualize audio input)
• Status indicators (API call in progress)
• Copy translation button
• Export transcript button

Features

• Auto-summary post-meeting (Claude analyse transcript)
• Export structured (audio + CN + FR + summary)
• Système de recherche (backlog meetings)
• Speaker diarization (qui parle)
• Multi-language support (JP, KR, etc)

---

📊 Métriques à Mesurer

Pendant le développement

• Build time: vcpkg + compile (first build vs incremental)
• Audio latency: Capture → buffer ready
• Whisper latency: Audio → transcription (varie selon chunk size)
• Claude latency: Texte CN → texte FR
• Total latency: Audio → Display
• Memory usage: RSS au démarrage vs après 30min
• CPU usage: % pendant recording + processing

Pendant l'usage réel

• Transcription accuracy: % mots corrects (subjectif, compare avec native speaker)
• Translation quality: Compréhensible ? Naturelle ?
• Crash rate: 0 sur 1h recording
• API cost: $ par meeting (tracker usage réel)

---

📝 Notes de Développement

Bugs Connus / TODO

• Pipeline.cpp ligne 150: std::put_time requiert <iomanip> (ajouter include)
• ThreadSafeQueue: Pas de clear() method (ajouter si besoin)
• Config: Pas de validation (e.g., sample_rate > 0)
• Error messages: Pas assez descriptifs (améliorer logging)
• main.cpp: Pas de signal handler (Ctrl+C ne sauvegarde pas audio)

Optimisations Possibles

• AudioBuffer: std::vector → mmap si très gros
• API clients: Connection pooling (httplib keep-alive)
• UI: Limit messages affichés (actuellement unbounded)

Code Quality

• Ajouter unit tests (Google Test)
• Ajouter CI/CD (GitHub Actions)
• Ajouter pre-commit hooks (clang-format)
• Documenter API avec Doxygen

---

🎓 Ressources Utiles

Documentation APIs

• Whisper API
• Claude API
• PortAudio
• ImGui

Samples Audio Chinois

• YouTube (utiliser youtube-dl)
• Tatoeba (phrases chinoises)
• Common Voice (dataset open)

Debug Tools

• arecord -l: Liste microphones disponibles
• aplay test.wav: Play WAV file
• valgrind --leak-check=full ./SecondVoice: Check memory leaks
• gdb ./SecondVoice: Debug crashes
• strace ./SecondVoice: Trace syscalls

---

🚦 Status Tracking

Phase 1 - Setup (DONE ✅)

• ✅ Structure projet
• ✅ CMake + vcpkg
• ✅ Code complet implémenté
• ✅ Documentation

Phase 2 - Build & Test (CURRENT)

• ⬜ Setup vcpkg + dépendances
• ⬜ Premier build réussi
• ⬜ Test audio capture
• ⬜ Test Whisper API
• ⬜ Test Claude API
• ⬜ Test pipeline complet

Phase 3 - Debug & Tuning

• ⬜ Fix build errors
• ⬜ Fix runtime errors
• ⬜ Optimiser latence
• ⬜ Valider qualité transcription/traduction

Phase 4 - Real-World Test

• ⬜ Test avec sample audio chinois
• ⬜ Test recording 30min sans crash
• ⬜ Test en condition réelle (meeting avec Tingting)

---

Next immediate action: Setup vcpkg et lancer ./build.sh

Bonne chance ! 🚀