jhonny-editor/code/engine/integracoes/audio/modelos_de_analise_musical.py

"""
Modelos internos para representar análises de músicas instrumentais.

Este módulo define somente os dados produzidos pela análise. Ele não importa
Essentia, não lê arquivos e não transforma o resultado em texto para a
interface.
"""

from dataclasses import dataclass, field
from pathlib import Path


@dataclass(frozen=True)
class PontuacaoDeEtiqueta:
    """Representa uma etiqueta musical e a confiança calculada para ela."""

    etiqueta: str
    confianca: float


@dataclass(frozen=True)
class ResultadoDaAnaliseMusical:
    """
    Representa os descritores calculados para uma música instrumental.

    A classe mantém valores objetivos, como BPM e tonalidade, além das
    classificações fornecidas pelos modelos disponíveis. Ela não afirma uma
    interpretação definitiva da intenção artística da música.
    """

    caminho_do_arquivo: Path
    duracao_em_segundos: float | None = None
    batidas_por_minuto: float | None = None
    tonalidade: str | None = None
    modo: str | None = None
    intensidade: float | None = None
    dancabilidade: float | None = None
    generos: tuple[str, ...] = field(default_factory=tuple)
    humores: tuple[str, ...] = field(default_factory=tuple)
    instrumentos: tuple[str, ...] = field(default_factory=tuple)
    etiquetas: tuple[str, ...] = field(default_factory=tuple)
    pontuacoes_de_genero: tuple[PontuacaoDeEtiqueta, ...] = field(default_factory=tuple)
    pontuacoes_de_humor: tuple[PontuacaoDeEtiqueta, ...] = field(default_factory=tuple)
    pontuacoes_de_tema: tuple[PontuacaoDeEtiqueta, ...] = field(default_factory=tuple)
    temas: tuple[str, ...] = field(default_factory=tuple)
    provedor: str = "Essentia"
    modelo: str | None = None