ser-standardizer 0.1.0__py3-none-any.whl

ser_standardizer/__init__.py

@@ -0,0 +1 @@
+from .api import load_datasets, load_audio, load_batch, listen, filters, normalize, extract_features

ser_standardizer/api.py

@@ -0,0 +1,83 @@
+import pandas as pd
+import os
+from pathlib import Path
+
+def load_datasets(datasets):
+    if isinstance(datasets, str):
+        target_datasets = [datasets]
+    else:
+        target_datasets = datasets
+
+    dataframes = []
+    DATA_DIR = os.path.join(Path.home(), ".ser_standardizer_data")
+    
+    for name in target_datasets:
+        file_path = os.path.join(DATA_DIR, f"process_{name}.csv")
+        if not file_path or not os.path.exists(file_path):
+            raise FileNotFoundError(
+                f"O dataset '{name}' não foi encontrado. "
+                f"Certifique-se de ter rodado: ser-std --dataset {name} ..."
+            )
+        df = pd.read_csv(file_path)
+        dataframes.append(df)
+
+    if not dataframes:
+        raise ValueError("Nenhum dataset válido foi fornecido.")
+        
+    return pd.concat(dataframes, ignore_index=True)
+
+def filters(df, datasets=None, emotions=None, genders=None, languages=None, speakers=None):
+    mask = pd.Series([True] * len(df), index=df.index)
+
+    def to_list(val):
+        if isinstance(val, str):
+            return [val]
+        return val
+
+    if datasets:
+        target = [x.lower() for x in to_list(datasets)]
+        mask = mask & df['dataset'].str.lower().isin(target)
+
+    if emotions:
+        target = [x.lower() for x in to_list(emotions)]
+        mask = mask & df['emotion'].str.lower().isin(target)
+
+    if genders:
+        target = [x.lower() for x in to_list(genders)]
+        mask = mask & df['gender'].str.lower().isin(target)
+
+    if languages:
+        target = [x.lower() for x in to_list(languages)]
+        mask = mask & df['language'].str.lower().isin(target)
+
+    if speakers:
+        target = [x.lower() for x in to_list(speakers)]
+        mask = mask & df['speaker_id'].str.lower().isin(target)
+
+    print(f"Filtro aplicado. Restaram {len(df[mask])} amostras.")
+    return df[mask].copy()
+
+def normalize(features, group, eps=1e-8):
+    """Aplica z-score por grupo em `features` (ex.: por dataset ou locutor)."""
+    g = group.reindex(features.index)
+    out = features.groupby(g).transform(
+        lambda c: (c - c.mean()) / (c.std(ddof=0) + eps)
+    )
+    return out.fillna(0.0)
+
+try:
+    from .features.preprocessing import listen, load_audio, load_batch
+    from .features.extractor import extract_features
+    FEATURES_AVAILABLE = True
+
+except ImportError:
+    FEATURES_AVAILABLE = False
+    
+    def _missing_deps_error(*args, **kwargs):
+        raise ImportError(
+            "Esta função requer o submódulo de extração acústica.\n"
+            "Para utilizá-la, reinstale o pacote com as dependências completas:\n\n"
+            "    pip install '.[features]'"
+        )
+        
+    listen = load_audio = load_batch = extract_features = _missing_deps_error

ser_standardizer/features/__init__.py

@@ -0,0 +1,3 @@
+# Módulo opcional (instale com `pip install "ser-standardizer[features]"`).
+# Sem imports aqui: os submódulos são importados sob demanda em api.py,
+# dentro de try/except ImportError.

ser_standardizer/features/extractor.py

@@ -0,0 +1,97 @@
+import pandas as pd
+import numpy as np
+from tqdm.auto import tqdm
+import opensmile
+from .preprocessing import load_audio, remove_silence
+
+def extract_features(df, feature_set='eGeMAPS', feature_level='functionals', use_vad=False, sr=16000):
+    """
+    Extrai características acústicas utilizando o openSMILE.
+    
+    Args:
+        df: DataFrame contendo a coluna 'file_path'.
+        feature_set: 'eGeMAPS' ou 'ComParE' (padrões validados na literatura).
+        feature_level: 'functionals' (estatísticas globais por arquivo) ou 'llds' (nível de frame).
+        use_vad: Se True, remove silêncios baseados na energia RMS. 
+                 ATENÇÃO: Permitido apenas quando feature_level='llds'.
+        sr: Taxa de amostragem esperada.
+        
+    Returns:
+        Um novo pd.DataFrame contendo as features. 
+        Para 'functionals', mantém o índice original.
+        Para 'llds', adiciona o índice original ('file_idx') para cruzamento de metadados.
+    """
+
+    if use_vad and feature_level.lower() == 'functionals':
+        raise ValueError(
+            "Erro de Metodologia: A aplicação de VAD no áudio bruto antes da extração "
+            "de funcionais corrompe as métricas temporais padronizadas do openSMILE "
+            "(como taxa de fala e proporção de pausas) e introduz artefatos no espectro. \n"
+            "-> Para extrair 'functionals' padronizados, defina use_vad=False. \n"
+            "-> O uso de use_vad=True é permitido apenas para extração no nível de frame ('llds')."
+        )
+
+    if feature_set.lower() == 'egemaps':
+        fset = opensmile.FeatureSet.eGeMAPSv02
+    elif feature_set.lower() == 'compare':
+        fset = opensmile.FeatureSet.ComParE_2016
+    else:
+        raise ValueError("Conjunto não suportado. Escolha 'eGeMAPS' ou 'ComParE'.")
+
+    # 2. Definir o Nível da Extração
+    if feature_level.lower() == 'functionals':
+        flevel = opensmile.FeatureLevel.Functionals
+        level_name = "Functionals"
+    elif feature_level.lower() in ['lld', 'llds']:
+        flevel = opensmile.FeatureLevel.LowLevelDescriptors
+        level_name = "LowLevelDescriptors"
+    else:
+        raise ValueError("Nível não suportado. Escolha 'functionals' ou 'llds'.")
+
+    print(f"Inicializando openSMILE ({feature_set} - {level_name})...")
+    smile = opensmile.Smile(
+        feature_set=fset,
+        feature_level=flevel,
+    )
+    
+    features_list = []
+    
+    for idx in tqdm(df.index, desc=f"Extraindo características ({level_name})"):
+        file_path = df.loc[idx, 'file_path']
+        
+        try:
+            if use_vad:
+                audio = load_audio(df, idx, sr=sr)
+                audio_clean = remove_silence(audio, sr=sr)
+                
+                if len(audio_clean) == 0:
+                    audio_clean = np.zeros(sr)
+                    
+                feat_df = smile.process_signal(audio_clean, sr)
+            else:
+                feat_df = smile.process_file(file_path)
+            
+            if flevel == opensmile.FeatureLevel.Functionals:
+                feat_series = feat_df.iloc[0].rename(idx)
+                features_list.append(feat_series)
+            else:
+                feat_df['file_idx'] = idx
+                features_list.append(feat_df)
+                
+        except Exception as e:
+            print(f"Erro na extração do índice {idx}: {e}")
+            if flevel == opensmile.FeatureLevel.Functionals:
+                features_list.append(pd.Series(dtype=float, name=idx))
+            else:
+                features_list.append(pd.DataFrame({'file_idx': [idx]}))
+
+    print("Consolidando matriz de features...")
+    
+    if flevel == opensmile.FeatureLevel.Functionals:
+        result_df = pd.DataFrame(features_list)
+    else:
+        result_df = pd.concat(features_list)
+        if 'file_idx' in result_df.columns:
+            result_df = result_df.set_index('file_idx', append=True)
+            
+    return result_df

ser_standardizer/features/preprocessing.py

@@ -0,0 +1,92 @@
+import soundfile as sf
+import scipy.signal
+import numpy as np
+from IPython.display import Audio, display
+from tqdm.auto import tqdm
+import noisereduce as nr
+
+def scipy_load(path, target_sr=None):
+
+    audio, native_sr = sf.read(path)
+
+    if audio.ndim > 1:
+        audio = np.mean(audio, axis=1)
+
+    if target_sr is not None and native_sr != target_sr:
+        num_samples = round(len(audio) * float(target_sr) / native_sr)
+        audio = scipy.signal.resample(audio, num_samples)
+        return audio, target_sr
+
+    return audio, native_sr
+
+def remove_silence(audio, sr=16000, frame_length=2048, hop_length=512, threshold=0.25):
+    audio_clean = nr.reduce_noise(y=audio, sr=sr)
+
+    n_frames = 1 + (len(audio_clean) - frame_length) // hop_length
+    if n_frames <= 0:
+        return audio_clean
+
+    rms = np.array([
+        np.sqrt(np.mean(audio_clean[i*hop_length : i*hop_length + frame_length] ** 2))
+        for i in range(n_frames)
+    ])
+
+    max_rms = np.max(rms)
+    if max_rms == 0:
+        return np.array([])
+
+    rms_norm = rms / max_rms
+    speech_mask = rms_norm > threshold
+
+    sample_mask = np.zeros(len(audio_clean), dtype=bool)
+    for i, active in enumerate(speech_mask):
+        if active:
+            start = i * hop_length
+            end = min(start + hop_length, len(audio_clean))
+            sample_mask[start:end] = True
+
+    return audio_clean[sample_mask]
+
+def listen(df, index):
+    if index not in df.index:
+        print(f"Aviso: Não há nenhum áudio disponível com o índice {index}.")
+        return
+
+    path = df.loc[index, 'file_path']
+    emotion = df.loc[index, 'emotion']
+    
+    print(f"Tocando áudio {index} | Emoção: {emotion}")
+    display(Audio(filename=path))
+
+def load_audio(df, index, sr=16000):
+    if index not in df.index:
+        raise IndexError("Índice não encontrado no Dataset.")
+    path = df.loc[index, 'file_path']
+    audio, _ = scipy_load(path, target_sr=sr)
+    return audio
+
+def load_batch(df, begin, end, sr=16000, max_1000=True):
+    qtd = end - begin
+    if qtd > 1000 and max_1000:
+        raise ValueError(f"Você tentou carregar {qtd} áudios. O limite é 1000. Defina max_1000=False se tiver certeza.")
+
+    batch = []
+    subset_indices = df.index[begin:end]
+
+    for idx in tqdm(subset_indices, desc="Carregando áudios"):
+        try:
+            audio = load_audio(df, idx, sr)
+            batch.append(audio)
+        except Exception as e:
+            print(f"Erro ao carregar índice {idx}: {e}")
+            batch.append(None)
+
+    max_len = max(len(x) for x in batch if x is not None)
+    padded_batch = np.zeros((len(batch), max_len), dtype=np.float32)
+
+    for i, audio in enumerate(batch):
+        if audio is not None:
+            padded_batch[i, :audio.shape[0]] = audio
+            
+    return padded_batch
+

ser_standardizer/loaders/__init__.py

@@ -0,0 +1,21 @@
+from .crema_d import process as process_crema
+from .iemocap import process as process_iemocap
+from .msp_improv import process as process_msp
+from .msp_podcast import process as process_msp_podcast
+from .emouerj import process as process_emouerj
+from .ravdess import process as process_ravdess
+from .emodb import process as process_emodb
+
+# Dicionário que mapeia o nome do dataset (string) para a função de processamento
+DATASET_LOADERS = {
+    'crema_d': process_crema,
+    'iemocap': process_iemocap,
+    'msp_improv': process_msp,
+    'msp_podcast': process_msp_podcast,
+    'emouerj': process_emouerj,
+    'ravdess': process_ravdess,
+    'emodb': process_emodb
+}
+
+def get_available_datasets():
+    return list(DATASET_LOADERS.keys())

ser_standardizer/loaders/crema_d.py

@@ -0,0 +1,125 @@
+import os
+import pandas as pd
+
+SENTENCE_MAP = {
+    "IEO": "It's eleven o'clock.",
+    "TIE": "That is exactly what happened.",
+    "IOM": "I'm on my way to the meeting.",
+    "IWW": "I wonder what this is about.",
+    "TAI": "The airplane is almost full.",
+    "MTI": "Maybe tomorrow it will be cold.",
+    "IWL": "I would like a new alarm clock.",
+    "ITH": "I think I have a cold.",
+    "DFA": "Don't forget a jacket.",
+    "ITS": "I think I'll wear my new suit.",
+    "TSI": "The surface is slick.",
+    "WSI": "We'll stop in a couple of minutes."
+}
+
+EMOTION_MAP = {
+    'A': 'Anger',
+    'D': 'Disgust',
+    'F': 'Fear',
+    'H': 'Happy',
+    'S': 'Sad',
+    'N': 'Neutral',
+}
+
+def process(base_dir):
+    """
+    Processa todos os arquivos de áudio do dataset CREMA-D,
+    consolida os metadados e retorna um DataFrame padronizado.
+    
+    Args:
+        base_dir (str): O caminho raiz para o dataset CREMA-D 
+                        (ex: ".../data/CREMA-D")
+
+    Returns:
+        pandas.DataFrame: Um DataFrame com metadados padronizados
+                          ou None se o processamento falhar.
+    """
+    print("Iniciando processamento do CREMA-D...")
+
+    # --- Definir Caminhos ---
+    AUDIO_DIR = os.path.join(base_dir, "AudioWAV")
+    DEMOGRAPHICS_FILE = os.path.join(base_dir, "VideoDemographics.csv")
+    RESPONSES_FILE = os.path.join(base_dir, "finishedResponses.csv")
+
+    # --- Carregar Metadados ---
+    print("Carregando arquivos de metadados do CREMA-D...")
+    try:
+        demographics_df = pd.read_csv(DEMOGRAPHICS_FILE).set_index('ActorID')
+        
+        raw_responses_df = pd.read_csv(RESPONSES_FILE, usecols=['queryType', 'clipName', 'respEmo'])
+        voice_responses_df = raw_responses_df[raw_responses_df['queryType'] == 1].copy()
+
+        votes_df = pd.crosstab(voice_responses_df['clipName'], voice_responses_df['respEmo'])
+        emotion_columns = ['A', 'D', 'F', 'H', 'S', 'N']
+                
+        votes_df['perceived_emotion_label'] = votes_df[emotion_columns].idxmax(axis=1)
+        print("Arquivos de metadados do CREMA-D carregados com sucesso.")
+
+    except Exception as e:
+        print(f"Erro ao carregar os arquivos CSV do CREMA-D: {e}")
+        return None
+
+    # --- Iterar sobre os arquivos de áudio ---
+    print(f"Iniciando processamento dos arquivos em: {AUDIO_DIR}")
+    all_file_data = []
+
+    for filename in os.listdir(AUDIO_DIR):
+        if filename.endswith('.wav'):
+            full_file_path = os.path.join(AUDIO_DIR, filename)
+            file_key = os.path.splitext(filename)[0]
+            
+            try:
+                # --- A. Extrair dados do NOME DO ARQUIVO ---
+                parts = file_key.split('_')
+                actor_id = int(parts[0])
+                sentence_id = parts[1]
+                intended_emotion_code = parts[2]
+                
+                # --- B. Buscar dados dos CSVs carregados ---
+                speaker_gender = demographics_df.loc[actor_id]['Sex']
+                sentence_text = SENTENCE_MAP.get(sentence_id, "Desconhecido")
+                perceived_emotion_code = votes_df.loc[file_key]['perceived_emotion_label']
+                
+                # --- C. Padronizar e Consolidar ---
+                file_info = {
+                    'dataset': 'CREMA_D',
+                    'file_path': full_file_path,
+                    # 'filename': filename,
+                    'speaker_id': f"crema_{actor_id}", 
+                    'gender': speaker_gender,
+                    'language': 'en',
+                    'sentence_text': sentence_text,
+                    'emotion': EMOTION_MAP.get(perceived_emotion_code, perceived_emotion_code),
+                }
+                
+                all_file_data.append(file_info)
+
+            except KeyError as e:
+                print(f"Aviso: Não foi possível encontrar metadados para {filename}. Chave não encontrada: {e}. Pulando...")
+            except Exception as e:
+                print(f"Erro ao processar o arquivo {filename}: {e}. Pulando...")
+
+    print(f"Processamento do CREMA-D concluído. {len(all_file_data)} arquivos processados.")
+
+    if not all_file_data:
+        return None
+
+    # --- 4. Criar e Retornar o DataFrame ---
+    final_df = pd.DataFrame(all_file_data)
+    
+    # Reordenar colunas para um layout padrão
+    standard_columns = [
+        'dataset', 'file_path', 'speaker_id', 'gender',
+        'emotion', 'sentence_text', 'language'
+    ]
+    
+    # Adiciona colunas que podem não existir no DF final (caso dê erro em todas)
+    for col in standard_columns:
+        if col not in final_df:
+            final_df[col] = pd.NA
+            
+    return final_df[standard_columns]

ser_standardizer/loaders/emodb.py

@@ -0,0 +1,121 @@
+import os
+import pandas as pd
+
+# EmoDB (Berlin Database of Emotional Speech) — alemão.
+# Formato do nome do arquivo: SSTTTEV.wav
+#   SS  -> número do locutor (2 dígitos)
+#   TTT -> código do texto (ex.: a01, b03)
+#   E   -> letra da emoção (alemão)
+#   V   -> versão (a, b, c, ...) quando há mais de uma gravação
+
+# Letras de emoção (iniciais em alemão) mapeadas para o rótulo padrão do repo.
+#   W = Wut (raiva), L = Langeweile (tédio), E = Ekel (nojo),
+#   A = Angst (medo), F = Freude (alegria), T = Trauer (tristeza), N = Neutral
+EMOTION_MAP = {
+    'W': 'Anger',
+    'L': 'Boredom',
+    'E': 'Disgust',
+    'A': 'Fear',
+    'F': 'Happy',
+    'T': 'Sad',
+    'N': 'Neutral',
+}
+
+# Gênero de cada um dos 10 locutores (conforme documentação oficial do EmoDB).
+SPEAKER_GENDER = {
+    '03': 'Male',
+    '08': 'Female',
+    '09': 'Female',
+    '10': 'Male',
+    '11': 'Male',
+    '12': 'Male',
+    '13': 'Female',
+    '14': 'Female',
+    '15': 'Male',
+    '16': 'Female',
+}
+
+# Frases em alemão associadas a cada código de texto.
+SENTENCE_MAP = {
+    'a01': "Der Lappen liegt auf dem Eisschrank.",
+    'a02': "Das will sie am Mittwoch abgeben.",
+    'a04': "Heute abend könnte ich es ihm sagen.",
+    'a05': "Das schwarze Stück Papier befindet sich da oben neben dem Holzstück.",
+    'a07': "In sieben Stunden wird es soweit sein.",
+    'b01': "Was sind denn das für Tüten, die da unter dem Tisch stehen?",
+    'b02': "Sie haben es gerade hochgetragen und jetzt gehen sie wieder runter.",
+    'b03': "An den Wochenenden bin ich jetzt immer nach Hause gefahren und habe Agnes besucht.",
+    'b09': "Ich will das eben wegbringen und dann mit Karl was trinken gehen.",
+    'b10': "Die wird auf dem Platz sein, wo wir sie immer hinlegen.",
+}
+
+
+def process(base_dir):
+    """
+    Processa o dataset EmoDB (Berlin Database of Emotional Speech).
+
+    A estrutura esperada é uma pasta raiz contendo os arquivos .wav
+    (as pastas oficiais EmoDB_1/ e EmoDB_2/ podem ser extraídas dentro dela;
+    a busca é recursiva).
+
+    Args:
+        base_dir (str): Caminho raiz onde os .wav do EmoDB estão salvos.
+
+    Returns:
+        pandas.DataFrame: DataFrame padronizado ou None se nada for encontrado.
+    """
+    print("Iniciando processamento do EmoDB...")
+
+    all_file_data = []
+
+    for root, dirs, files in os.walk(base_dir):
+        for filename in files:
+            if not filename.lower().endswith('.wav'):
+                continue
+
+            file_key = os.path.splitext(filename)[0]
+
+            # Nome padrão do EmoDB tem 7 caracteres: SS TTT E V
+            if len(file_key) != 7:
+                print(f"Nome fora do padrão, ignorado: {filename}")
+                continue
+
+            speaker_id = file_key[0:2]
+            text_code = file_key[2:5]
+            emotion_code = file_key[5]
+            # file_key[6] é a versão, não usada no schema padrão.
+
+            emotion = EMOTION_MAP.get(emotion_code)
+            if emotion is None:
+                print(f"Emoção desconhecida ({emotion_code}) em {filename}, ignorado.")
+                continue
+
+            file_info = {
+                'dataset': 'EmoDB',
+                'file_path': os.path.join(root, filename),
+                'speaker_id': f"emodb_{speaker_id}",
+                'gender': SPEAKER_GENDER.get(speaker_id, pd.NA),
+                'language': 'de',
+                'emotion': emotion,
+                'sentence_text': SENTENCE_MAP.get(text_code, "Unknown"),
+            }
+
+            all_file_data.append(file_info)
+
+    print(f"Processamento do EmoDB concluído. {len(all_file_data)} arquivos processados.")
+
+    if not all_file_data:
+        return None
+
+    final_df = pd.DataFrame(all_file_data)
+
+    standard_columns = [
+        'dataset', 'file_path', 'speaker_id', 'gender',
+        'emotion', 'sentence_text', 'language'
+    ]
+
+    for col in standard_columns:
+        if col not in final_df:
+            final_df[col] = pd.NA
+
+    return final_df[standard_columns]

ser_standardizer/loaders/emouerj.py

@@ -0,0 +1,72 @@
+import pandas as pd
+import audb
+
+EMOTION_MAP = {
+    'anger': 'Anger',
+    'happiness': 'Happy',
+    'sadness': 'Sad',
+    'neutral': 'Neutral'
+}
+
+def process(base_dir=None):
+    """
+    Carrega o dataset EmoUERJ via audb e padroniza para o formato do projeto.
+    
+    Args:
+        base_dir (str): Opcional neste caso, pois o audb gerencia o cache.
+                        Pode ser usado para definir onde o audb salva os arquivos
+                        se você configurar o cache localmente.
+
+    Returns:
+        pandas.DataFrame: DataFrame padronizado.
+    """
+    print("Iniciando processamento do EmoUERJ via audb...")
+
+    try:
+        db = audb.load("emouerj", version="1.0.0", verbose=False)
+
+        original_df = db.get("emotion", ["gender", "speaker", "take"])
+        
+        original_df['file_path'] = original_df.index
+        original_df = original_df.reset_index(drop=True)
+
+        print(f"EmoUERJ carregado. Processando {len(original_df)} arquivos...")
+
+        all_file_data = []
+
+        for row in original_df.itertuples():
+            try:
+                original_emotion = row.emotion
+                speaker = row.speaker
+                gender = row.gender.capitalize()
+                full_path = row.file_path
+                file_info = {
+                    'dataset': 'EmoUERJ',
+                    'file_path': full_path,
+                    'speaker_id': f"emouerj_{speaker}",
+                    'gender': gender,
+                    'language': 'pt-br',
+                    'sentence_text': pd.NA,
+                    'emotion': EMOTION_MAP.get(original_emotion, original_emotion),
+                }
+                all_file_data.append(file_info)
+            except Exception as e:
+                print(f"Erro ao processar linha do EmoUERJ: {e}")
+
+        final_df = pd.DataFrame(all_file_data)
+        
+        standard_columns = [
+            'dataset', 'file_path', 'speaker_id', 'gender',
+            'emotion', 'sentence_text', 'language'
+        ]
+
+        for col in standard_columns:
+            if col not in final_df:
+                final_df[col] = pd.NA
+
+        print(f"Processamento do EmoUERJ concluído. {len(final_df)} arquivos.")
+        return final_df[standard_columns]
+
+    except Exception as e:
+        print(f"Falha crítica ao carregar EmoUERJ via audb: {e}")
+        return None