feat: Voice Interaction and Integrated Explanatory Video — Student Space

[MaryamAjahoud]

🎯 Overview

This PR implements two new features for the student learning space:

• Voice Interaction: students can ask questions verbally and listen to AI responses
• Integrated Explanatory Video: display a YouTube video directly inside the chat without leaving the workspace

---

🎤 Voice Interaction with AI

What was implemented

• 🎤 Voice input via Web Speech API (SpeechRecognition) — FR/EN support
• 🔊 Text-to-speech for AI responses via SpeechSynthesis API
• 🎵 Animated mic button with real-time waveform visualizer (AudioContext)
• 📝 Live transcription displayed in real time while listening
• 🌍 FR 🇫🇷 / EN 🇬🇧 toggle button — language forced on every AI message

Screenshots

Mic button + waveform visualizer:

---

🎥 Integrated Explanatory Video in Chat

What was implemented

• 🎥 "Generate Explanatory Video" button in the pedagogical shortcuts panel
• 🔍 YouTube search via server-side scraping (no API key required)
• ▶️ Lite Embed: thumbnail → youtube-nocookie.com iframe on click (avoids CORS)
• 🎙️ Dedicated mic inside the video panel to dictate the search topic
• 🔒 UI lock: main chat input blocked while video panel is active
• 📌 [YOUTUBE: ID] tag parsed automatically in AI responses

Screenshots

Video search panel with mic button:

Video playing inline in the chat:

---

📚 Documentation Added

• docs/uml_diagrams.md — UML diagrams (class, activity, sequence)
• docs/uml_preview.html — Interactive HTML diagram viewer with explanations
• docs/technical_documentation.md — Full technical reference

---

✅ Manual Tests

• FR mic → transcription → AI responds in French
• EN mic → transcription → AI responds in English
• 🔊 button reads AI response in correct language
• Video search (text + mic) → results → inline playback
• Video navigation ‹ › between thumbnails
• Closing video → normal state, no accidental message sent
• History: navigation, search, bulk delete

[Oumaima-elkhoummassi]

Hi @MaryamAjahoud
Documentation review — technical_documentation.md, uml_diagrams.md, and uml_preview.html checked.

Strong work on technical_documentation.md

Missing:

1. No user guide - technical_documentation.md is a technical reference, but there's no step-by-step guide for a student (how to activate the mic, what happens if permission is denied, how to search for a video, how to navigate between videos). Since both features have a visible UI, a [feature]-user-guide.md is expected.

2. uml_preview.html - an HTML file in docs/ isn't standard and it's not referenced from any .md file. Either convert its content to markdown, or add a line in technical_documentation.md pointing to it.

3. PR description is missing the formal format used in other PRs: a "Why" section (linked issue), a changelog (Added / Changed / Fixed), and a checklist. Could you add these?

Please add the user guide and fix items 2-3 before approval.

[MaryamAjahoud]

Hi @Oumaima-elkhoummassi! Thank you for the review.

1. User guide added → docs/voice-video-user-guide.md
2. uml_preview.html removed — The HTML file has been deleted. The Mermaid diagrams are now only in docs/uml_diagrams.md (renders natively on GitHub and in VS Code). A note was added in technical_documentation.md explaining how to view the diagrams.
3. PR description updated → Added "Why", "Changelog" (Added/Changed/Fixed), and "PR Checklist" sections.

Please let me know if anything else needs adjustment!

[pr-elhajji]

Hi, thk for contuning dev.
just the design style is note aligned woth opentutorai style

[Eziane]

Salam @MaryamAjahoud,
Appreciate the work. Please resolve the merge conflicts so we can review it.

[Eziane]

Thanks @MaryamAjahoud for the follow-ups on the docs/description — those three items from @Oumaima-elkhoummassi's review are all clearly addressed. The design-style comment also looks handled by the latest commit.

Main thing I found: the new backend route for video search has a few real problems.

1. This will break CI outright. gateway/http/routers/youtube.py does import requests at the top, but requests is only in requirements.txt, not requirements-ci.txt (which is what CI actually installs). Since gateway/http/app.py imports this router unconditionally, and tests/conftest.py imports create_app to build the test client, every single backend test will fail to even collect with ModuleNotFoundError: No module named 'requests'. Easiest fix: swap to httpx (already in requirements-ci.txt, already used for outbound calls in ai/providers/proxy.py) instead of adding requests to another requirements file — see point 2 for why that's the better fix anyway.

2. The endpoint has no auth and blocks the event loop. youtube.py L19-26: this is the only feature route out of 25 routers with no Depends(get_current_user) (the only other two unauthenticated routes are /health and app info, which are meant to be public). On top of that, it's async def but calls the synchronous requests.get(...) directly — that blocks the whole event loop for up to 8s per call. Put together: anyone, logged in or not, can send a handful of concurrent requests and stall the API for every other user. Moving to httpx.AsyncClient (or ai/providers/proxy.py's pattern) plus adding the standard auth dependency fixes both at once.

3. No service layer, no tests. The scraping + regex parsing lives directly in the router, skipping the repository/service pattern the rest of the app follows for new domains. And there's no tests/test_youtube.py at all — even a basic happy-path test would have caught issue Num1 locally before it hit CI.

4. Raw exceptions leak to the client. L47-48: except Exception as e: return JSONResponse({"error": str(e), ...}, 500) — sends internal error text straight back in the response. Log it server-side, return something generic instead.

5. ChatHistorySidebar.svelte's translation keys are French text, not English. L124-211 use things like $i18n.t('Historique'), $i18n.t('Rechercher...') as the key itself, instead of the project's convention of keying off the English string (see Sidebar.svelte's $i18n.t('Help')). None of these keys exist in en-US, fr-FR, or ar-MA's translation.json. Two effects: CI's i18n step (npm run i18n:parse + git diff --exit-code) will fail since it'll regenerate the locale files with new keys; and even once that's fixed, English/Arabic users will see raw French text in this sidebar since it was never actually wired through translation — it just happens to look right in French.

Smaller stuff, not blocking:

• The /youtube/search fetch call is inline in PedagogicalShortcuts.svelte (L110) instead of a ui/src/lib/apis/youtube/index.ts client — worth moving for consistency, and it also means this call is currently invisible to test_contract_coverage.py (which only scans ui/src/lib/apis/).

Good bones on the voice/video UX itself (the lite-embed thumbnail-then-iframe pattern is a nice touch to avoid loading cross-origin iframes eagerly). It's really the new backend surface that needs work before this can merge.