voxkit.analyzers

 1"""Analyzers observe datasets and link metadata. They
 2extract structured information at registration time (ingestion), producing CSV summaries
 3that can be visualized within VoxKit without rescanning the filesystem.
 4
 5API
 6---
 7- **AnalyzerManager.list_analyzers**: List registered analyzer IDs
 8- **AnalyzerManager.get_analyzer**: Retrieve analyzer instance by ID
 9- **AnalyzerManager.get_analyzers**: Get all registered analyzers
10
11Available Analyzers
12-------------------
13**DefaultAnalyzer**
14    Extracts speaker count and audio file counts per speaker directory.
15    Includes a bar chart visualization for quick dataset overview.
16
17**ClipDurationStatisticsAnalyzer**
18    Reads audio metadata to compute total, average, min, and max clip duration
19    per speaker. Includes a bar chart visualization of total duration.
20
21**AudioFormatProfileAnalyzer**
22    Reads audio metadata to surface dominant sample rate, channel count, and
23    flags files that deviate from the speaker's dominant format.
24
25Output Structure
26----------------
27Analyzer output is stored alongside dataset metadata::
28
29    ~/.voxkit/datasets/{dataset_id}/
30    ├── voxkit_dataset.json           # Dataset metadata
31    ├── {analyzer_name}_summary.csv   # Analyzer output
32    └── alignments/                   # Alignment outputs
33
34Notes
35-----
36- Analyzers run during dataset registration (ingestion)
37- Each analyzer's ``name`` property serves as its unique identifier
38- Output is a list of dicts where keys become CSV column headers
39- Custom visualizations can be provided via the ``visualize`` method
40"""
41
42from __future__ import annotations
43
44from typing import List
45
46from .audio_format_profile import AudioFormatProfileAnalyzer
47from .base import DatasetAnalyzer
48from .clip_duration_statistics import ClipDurationStatisticsAnalyzer
49from .default_analyzer import DefaultAnalyzer
50
51
52class AnalyzerManager:
53    """
54    Manager for registered dataset analyzers.
55
56    Provides a unified interface to list and retrieve registered analyzer
57    implementations.
58    """
59
60    def __init__(self, analyzers: dict[str, DatasetAnalyzer]):
61        # Expect a mapping of id -> DatasetAnalyzer instance
62        self._analyzers = analyzers
63
64    def list_analyzers(self) -> List[str]:
65        """Return a list of registered analyzer IDs."""
66        keys = list(self._analyzers.keys())
67        return keys
68
69    def get_analyzers(self) -> dict[str, DatasetAnalyzer]:
70        """Return the registered analyzers mapping."""
71        return self._analyzers
72
73    def get_analyzer(self, analyzer_id: str) -> DatasetAnalyzer:
74        """Return the registered analyzer instance for the given ID."""
75        try:
76            return self._analyzers[analyzer_id]
77        except KeyError:
78            raise ValueError(f"No analyzer with id: {analyzer_id}")
79
80
81_default = DefaultAnalyzer()
82_duration = ClipDurationStatisticsAnalyzer()
83_format = AudioFormatProfileAnalyzer()
84
85# Singleton instance for unified export/interface
86ManageAnalyzers = AnalyzerManager(
87    {
88        _default.name: _default,
89        _duration.name: _duration,
90        _format.name: _format,
91    }
92)
93
94__all__ = [
95    "ManageAnalyzers",
96]