How mechamogeo/spectra works
Project type and purpose
• SPECTRA is a backend-only, RESTful API service for speech analysis (no web UI).
• It ingests audio files, extracts speech features, runs classification (read vs. spontaneous), then post-processes results (readability score + natural language explanation).
File structure
• Top level
• src/core/app.py → FastAPI entry point (API layer)
• src/core/dtos/ → Data Transfer Objects between layers
• src/use_cases/ → Business logic (“use case” layer)
• resources/audios/ → Static storage location for input audio
• Key patterns
• Clean Architecture: Layers are strictly separated (API → DTOs → Use Cases → External services)
• No databases—state is transient, files live on disk.
Extract additional insights from the README
• Architecture subsection already calls out “clean architecture.”
• External dependencies: FastAPI (HTTP), Parselmouth (speech-feature extraction), Faster-Whisper (ASR), FFmpeg (format conversion), Ollama via LangChain (LLM explanations), NumPy.
• Input/Output: Client → HTTP GET /analyze?file_name=… → JSON response.
Components and relationships
a. Main components
• Client (e.g., curl, Postman, or another service)
• API Layer (FastAPI in src/core/app.py)
• DTO Layer (src/core/dtos)
• Use-Case Services
– AudioContextAnalyzer
– SpeechClassifier
• External/Infrastructure Services
– FFmpeg (audio conversion)
– Parselmouth (feature extraction)
– Faster-Whisper (speech-to-text)
– Ollama LLM via LangChain (natural language explanation)
• Storage
– Local file storage (resources/audios/)
b. Relationships and data flows
1. Client → HTTP request → FastAPI (API Layer)
2. API Layer validates request → builds request DTO → passes to Use-Case Services
3. Use-Case Services orchestrate:
• Load audio from resources/audios/
• Call FFmpeg if format needs conversion → pass standardized audio blob
• Invoke Parselmouth to compute speech features (word length, pauses, rate)
• Invoke Faster-Whisper for transcription (if needed by classification)
• Combine features into readability score
• Call Ollama LLM via LangChain to generate human-readable explanation
4. Use-Case returns response DTO → API Layer serializes to JSON → HTTP response → Client
c. Architectural patterns and principles
• Clean / Hexagonal Architecture:
– Strict layering—outer layers depend on abstractions in inner layers only
• Single Responsibility Principle: each use-case class does one thing
• Dependency Injection: services take interfaces/DTOs rather than concrete objects
d. Key technologies/frameworks
• FastAPI for HTTP interface
• Parselmouth & NumPy for DSP / feature stats
• Faster-Whisper for speech recognition
• FFmpeg for format conversion
• LangChain + Ollama for LLM-based explanations
Essential details to capture
• Component names (exact folder/module names)
• Data contract names (DTO classes like AnalysisDTO, TranscriptionDTO)
• Sequence of calls through layers and external services
• Protocols (HTTP, local file I/O, library calls)