Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python
24.2 KB
Raw Blame
"""
Speaker identification and management.

This blueprint was auto-generated from app.py route extraction.
"""

import os
import json
import time
from datetime import datetime, timedelta
from flask import Blueprint, render_template, request, redirect, url_for, flash, jsonify, send_file, Response, current_app
from flask_login import login_required, current_user
from werkzeug.utils import secure_filename

from src.database import db
from src.models import *
from src.utils import *
from src.utils.ffmpeg_utils import extract_audio_segment, FFmpegError, FFmpegNotFoundError
from src.utils.ffprobe import get_codec_info, FFProbeError
from src.utils.search import LIKE_ESCAPE, contains_pattern
from src.services.speaker_embedding_matcher import find_matching_speakers
from src.services.speaker_snippets import get_speaker_snippets, get_speaker_recordings_with_snippets
from src.services.speaker_merge import merge_speakers, preview_merge, can_merge_speakers
from src.utils.localization import api_error, translate

# Create blueprint
speakers_bp = Blueprint('speakers', __name__)

# Configuration from environment
ENABLE_INQUIRE_MODE = os.environ.get('ENABLE_INQUIRE_MODE', 'false').lower() == 'true'
ENABLE_AUTO_DELETION = os.environ.get('ENABLE_AUTO_DELETION', 'false').lower() == 'true'
USERS_CAN_DELETE = os.environ.get('USERS_CAN_DELETE', 'true').lower() == 'true'
ENABLE_INTERNAL_SHARING = os.environ.get('ENABLE_INTERNAL_SHARING', 'false').lower() == 'true'
USE_ASR_ENDPOINT = os.environ.get('USE_ASR_ENDPOINT', 'false').lower() == 'true'

# Global helpers (will be injected from app)
has_recording_access = None
bcrypt = None
csrf = None
limiter = None

def init_speakers_helpers(**kwargs):
    """Initialize helper functions and extensions from app."""
    global has_recording_access, bcrypt, csrf, limiter
    has_recording_access = kwargs.get('has_recording_access')
    bcrypt = kwargs.get('bcrypt')
    csrf = kwargs.get('csrf')
    limiter = kwargs.get('limiter')


# --- Routes ---

@speakers_bp.route('/speakers', methods=['GET'])
@login_required
def get_speakers():
    """Get all speakers for the current user, ordered by usage frequency and recency."""
    try:
        speakers = Speaker.query.filter_by(user_id=current_user.id)\
                               .order_by(Speaker.use_count.desc(), Speaker.last_used.desc())\
                               .all()
        # Voice profile counts (samples, variants) from one query for all.
        from src.models import SpeakerVoiceSample
        from src.services.voice_profiles import voice_summary
        rows_by_speaker = {}
        for row in SpeakerVoiceSample.query.filter_by(user_id=current_user.id).all():
            rows_by_speaker.setdefault(row.speaker_id, []).append(row)
        out = []
        for speaker in speakers:
            item = speaker.to_dict()
            item['voice'] = voice_summary(speaker, rows_by_speaker.get(speaker.id, []))
            out.append(item)
        return jsonify(out)
    except Exception as e:
        current_app.logger.error(f"Error fetching speakers: {e}")
        return jsonify({'error': str(e)}), 500



@speakers_bp.route('/speakers/search', methods=['GET'])
@login_required
def search_speakers():
    """Search speakers by name for autocomplete functionality.

    With an empty ``q`` and ``top=1`` it returns the most-used speakers, so a
    name field can offer suggestions before anything is typed (#395).
    """
    try:
        query = request.args.get('q', '').strip()
        top = request.args.get('top', '').lower() in ('1', 'true')
        if not query and not top:
            return jsonify([])

        stmt = Speaker.query.filter_by(user_id=current_user.id)
        if query:
            stmt = stmt.filter(Speaker.name.ilike(contains_pattern(query), escape=LIKE_ESCAPE))
        speakers = stmt.order_by(Speaker.use_count.desc(), Speaker.last_used.desc())\
                       .limit(10)\
                       .all()
        
        return jsonify([speaker.to_dict() for speaker in speakers])
    except Exception as e:
        current_app.logger.error(f"Error searching speakers: {e}")
        return jsonify({'error': str(e)}), 500



@speakers_bp.route('/speakers', methods=['POST'])
@login_required
def create_speaker():
    """Create a new speaker or update existing one."""
    try:
        data = request.json
        name = data.get('name', '').strip()
        
        if not name:
            return jsonify(api_error('speaker_name_required')), 400
        
        # Check if speaker already exists for this user
        existing_speaker = Speaker.query.filter_by(user_id=current_user.id, name=name).first()
        
        if existing_speaker:
            # Update usage statistics
            existing_speaker.use_count += 1
            existing_speaker.last_used = datetime.utcnow()
            db.session.commit()
            return jsonify(existing_speaker.to_dict())
        else:
            # Create new speaker
            speaker = Speaker(
                name=name,
                user_id=current_user.id,
                use_count=1,
                created_at=datetime.utcnow(),
                last_used=datetime.utcnow()
            )
            db.session.add(speaker)
            db.session.commit()
            return jsonify(speaker.to_dict()), 201
            
    except Exception as e:
        db.session.rollback()
        current_app.logger.error(f"Error creating speaker: {e}")
        return jsonify({'error': str(e)}), 500



@speakers_bp.route('/speakers/<int:speaker_id>', methods=['PUT'])
@login_required
def update_speaker(speaker_id):
    """Update a speaker's name and cascade the change to all recordings."""
    try:
        speaker = Speaker.query.filter_by(id=speaker_id, user_id=current_user.id).first()
        if not speaker:
            return jsonify(api_error('speaker_not_found')), 404

        data = request.json
        new_name = data.get('name', '').strip()

        if not new_name:
            return jsonify(api_error('speaker_name_empty')), 400

        # Check if another speaker with this name already exists for this user
        existing_speaker = Speaker.query.filter_by(user_id=current_user.id, name=new_name).first()
        if existing_speaker and existing_speaker.id != speaker_id:
            return jsonify(api_error('speaker_name_exists', name=new_name)), 400

        # Store old name for updating transcript chunks and recordings
        old_name = speaker.name

        # Update the speaker name
        speaker.name = new_name

        # Cascade the new name to every recording of this user
        from src.services.speaker_merge import rename_speaker_in_recordings, refresh_renamed_recordings
        chunks_updated, renamed = rename_speaker_in_recordings(current_user.id, old_name, new_name,
                                                               speaker_id=speaker.id, new_speaker_id=speaker.id)
        recordings_updated = len(renamed)

        db.session.commit()
        refresh_renamed_recordings(renamed)

        current_app.logger.info(
            f"Updated speaker {speaker_id} from '{old_name}' to '{new_name}': "
            f"{chunks_updated} transcript chunks, {recordings_updated} recordings"
        )

        return jsonify({
            'success': True,
            'speaker': speaker.to_dict(),
            'chunks_updated': chunks_updated,
            'recordings_updated': recordings_updated
        })

    except Exception as e:
        db.session.rollback()
        current_app.logger.error(f"Error updating speaker: {e}")
        return jsonify({'error': str(e)}), 500


@speakers_bp.route('/speakers/<int:speaker_id>', methods=['DELETE'])
@login_required
def delete_speaker(speaker_id):
    """Delete a speaker."""
    try:
        speaker = Speaker.query.filter_by(id=speaker_id, user_id=current_user.id).first()
        if not speaker:
            return jsonify(api_error('speaker_not_found')), 404

        db.session.delete(speaker)
        db.session.commit()
        return jsonify({'success': True})

    except Exception as e:
        db.session.rollback()
        current_app.logger.error(f"Error deleting speaker: {e}")
        return jsonify({'error': str(e)}), 500



@speakers_bp.route('/speakers/delete_all', methods=['DELETE'])
@login_required
def delete_all_speakers():
    """Delete all speakers for the current user."""
    try:
        # Bulk delete skips ORM cascades, and SQLite does not enforce the
        # ON DELETE CASCADE rules, so the snippets and voice samples go first (#475).
        from src.models import SpeakerVoiceSample
        from src.models.speaker_snippet import SpeakerSnippet
        speaker_ids = db.session.query(Speaker.id).filter_by(user_id=current_user.id)
        SpeakerSnippet.query.filter(SpeakerSnippet.speaker_id.in_(speaker_ids)).delete(
            synchronize_session=False)
        SpeakerVoiceSample.query.filter_by(user_id=current_user.id).delete()
        deleted_count = Speaker.query.filter_by(user_id=current_user.id).delete()
        db.session.commit()
        return jsonify({'success': True, 'deleted_count': deleted_count})

    except Exception as e:
        db.session.rollback()
        current_app.logger.error(f"Error deleting all speakers: {e}")
        return jsonify({'error': str(e)}), 500


@speakers_bp.route('/speakers/suggestions/<int:recording_id>', methods=['GET'])
@login_required
def get_speaker_suggestions(recording_id):
    """
    Get speaker suggestions based on voice embeddings from a recording.

    For each speaker in the recording, returns matching speakers from the user's
    speaker database based on voice similarity.

    Returns:
        {
            'SPEAKER_00': [
                {'speaker_id': 5, 'name': 'John', 'similarity': 85.3, 'confidence': 0.92},
                ...
            ],
            'SPEAKER_01': [...],
            ...
        }
    """
    try:
        recording = db.session.get(Recording, recording_id)
        if not recording:
            return jsonify(api_error('recording_not_found')), 404

        if not has_recording_access(recording, current_user, require_edit=False):
            return jsonify(api_error('recording_access_denied')), 403

        # Get speaker embeddings from recording
        if not recording.speaker_embeddings:
            return jsonify({'suggestions': {}, 'message': translate('server.apiMessage.noSpeakerEmbeddings')}), 200

        # Matching compares each voice with every voice variant of each
        # person, within the recording's embedding space. The threshold is
        # calibrated from the space's own samples once there are enough; a
        # ?threshold= query parameter still overrides it.
        from src.services.voice_profiles import suggestions_for_recording
        threshold = request.args.get('threshold', type=float)
        suggestions = suggestions_for_recording(recording, current_user.id, threshold=threshold)

        return jsonify({
            'success': True,
            'suggestions': suggestions,
            'recording_id': recording_id
        })

    except Exception as e:
        current_app.logger.error(f"Error getting speaker suggestions: {e}")
        return jsonify({'error': str(e)}), 500


@speakers_bp.route('/speakers/<int:speaker_id>/snippets', methods=['GET'])
@login_required
def get_snippets(speaker_id):
    """
    Get representative speech snippets for a speaker.

    Returns recent quotes from recordings where this speaker appeared.
    """
    try:
        # Verify speaker belongs to user
        speaker = Speaker.query.filter_by(id=speaker_id, user_id=current_user.id).first()
        if not speaker:
            return jsonify(api_error('speaker_not_found')), 404

        limit = int(request.args.get('limit', 5))
        snippets = get_speaker_snippets(speaker_id, limit)

        return jsonify({
            'success': True,
            'speaker_id': speaker_id,
            'speaker_name': speaker.name,
            'snippets': snippets
        })

    except Exception as e:
        current_app.logger.error(f"Error getting speaker snippets: {e}")
        return jsonify({'error': str(e)}), 500


@speakers_bp.route('/speakers/<int:speaker_id>/recordings', methods=['GET'])
@login_required
def get_speaker_recordings(speaker_id):
    """
    Get list of recordings that contain snippets from this speaker.

    Returns recording metadata with snippet counts.
    """
    try:
        # Verify speaker belongs to user
        speaker = Speaker.query.filter_by(id=speaker_id, user_id=current_user.id).first()
        if not speaker:
            return jsonify(api_error('speaker_not_found')), 404

        recordings = get_speaker_recordings_with_snippets(speaker_id)

        return jsonify({
            'success': True,
            'speaker_id': speaker_id,
            'speaker_name': speaker.name,
            'recordings': recordings
        })

    except Exception as e:
        current_app.logger.error(f"Error getting speaker recordings: {e}")
        return jsonify({'error': str(e)}), 500


@speakers_bp.route('/speakers/<int:speaker_id>/voice_samples', methods=['GET'])
@login_required
def list_voice_samples(speaker_id):
    """The samples a person's voice profile is built from, newest first."""
    from src.models import SpeakerVoiceSample
    from src.services.voice_profiles import voice_summary, effective_space, current_space_id
    speaker = Speaker.query.filter_by(id=speaker_id, user_id=current_user.id).first()
    if not speaker:
        return jsonify(api_error('speaker_not_found')), 404
    rows = SpeakerVoiceSample.query.filter_by(speaker_id=speaker.id).all()
    titles = {}
    rec_ids = [r.recording_id for r in rows if r.recording_id]
    if rec_ids:
        for rec in Recording.query.filter(Recording.id.in_(rec_ids)).all():
            if has_recording_access(rec, current_user, require_edit=False):
                titles[rec.id] = rec.title
    current = effective_space(current_space_id())
    samples = []
    if not rows and speaker.average_embedding:
        # A profile from before samples existed: shown as one entry so it can
        # be seen and removed like any sample (removing it clears the profile).
        samples.append({'id': None, 'speaker_id': speaker.id, 'recording_id': None, 'label': None,
                        'source': 'legacy', 'weight': float(min(max(speaker.embedding_count or 1, 1), 5)),
                        'speech_seconds': None, 'space_id': None, 'recording_title': None,
                        'in_current_space': effective_space(None) == current,
                        'created_at': speaker.created_at.isoformat() if speaker.created_at else None})
    for r in sorted(rows, key=lambda r: r.updated_at or r.created_at, reverse=True):
        item = r.to_dict()
        item['recording_title'] = titles.get(r.recording_id)
        if r.recording_id not in titles:
            item['recording_id'] = None  # deleted, or no longer shared with this user
        item['in_current_space'] = effective_space(r.space_id) == current
        samples.append(item)
    return jsonify({'summary': voice_summary(speaker, rows), 'samples': samples})


@speakers_bp.route('/speakers/<int:speaker_id>/voice_samples/<int:sample_id>', methods=['DELETE'])
@login_required
def delete_voice_sample(speaker_id, sample_id):
    """Remove one sample; the person's voice variants are rebuilt without it."""
    from src.models import SpeakerVoiceSample
    from src.services import voice_profiles as vp
    speaker = Speaker.query.filter_by(id=speaker_id, user_id=current_user.id).first()
    if not speaker:
        return jsonify(api_error('speaker_not_found')), 404
    sample = SpeakerVoiceSample.query.filter_by(id=sample_id, speaker_id=speaker.id).first()
    if not sample:
        return jsonify(api_error('sample_not_found')), 404
    try:
        db.session.delete(sample)
        db.session.flush()
        vp.refresh_speaker_summary(speaker)
        vp._calibration_cache.clear()
        db.session.commit()
        return jsonify({'success': True, 'summary': vp.voice_summary(speaker),
                        'speaker': speaker.to_dict()})
    except Exception as e:
        db.session.rollback()
        current_app.logger.error(f"Error removing voice sample {sample_id}: {e}")
        return jsonify(api_error('sample_remove_failed')), 500


@speakers_bp.route('/speakers/<int:speaker_id>/clear_embeddings', methods=['POST'])
@login_required
def clear_speaker_embeddings(speaker_id):
    """
    Clear all voice embeddings for a speaker.

    This removes all voice recognition data but keeps the speaker name and metadata.
    Useful for resetting voice profiles or removing outdated/incorrect voice data.
    """
    try:
        # Verify speaker belongs to user
        speaker = Speaker.query.filter_by(id=speaker_id, user_id=current_user.id).first()
        if not speaker:
            return jsonify(api_error('speaker_not_found')), 404

        # Clear all embeddings. NOTE: the matchable vector lives in the
        # `average_embedding` column (and the history in `embeddings_history`)
        # — there is NO `voice_embeddings` column. The previous code set a
        # phantom `voice_embeddings` attribute that never persisted, so the
        # real average_embedding survived and voice matching kept working
        # after a "clear". Null out the actual columns.
        from src.models import SpeakerVoiceSample
        SpeakerVoiceSample.query.filter_by(speaker_id=speaker.id).delete()
        speaker.average_embedding = None
        speaker.embeddings_history = None
        speaker.embedding_count = 0
        speaker.confidence_score = None

        db.session.commit()

        current_app.logger.info(f"Cleared voice embeddings for speaker {speaker_id} ({speaker.name})")

        return jsonify({
            'success': True,
            'message': translate('server.apiMessage.voiceProfileCleared', name=speaker.name),
            'speaker': {
                'id': speaker.id,
                'name': speaker.name,
                'embedding_count': 0
            }
        })

    except Exception as e:
        db.session.rollback()
        current_app.logger.error(f"Error clearing speaker embeddings: {e}")
        return jsonify({'error': str(e)}), 500


@speakers_bp.route('/speakers/snippet-audio/<int:recording_id>', methods=['GET'])
@login_required
def get_snippet_audio(recording_id):
    """
    Serve a short audio snippet from a recording.

    Query parameters:
        start: Start time in seconds (float)
        duration: Duration in seconds (float, max 5.0)

    Returns:
        Audio file segment in the original format
    """
    import tempfile
    import os
    from pathlib import Path

    try:
        # Get query parameters
        start_time = float(request.args.get('start', 0))
        duration = min(float(request.args.get('duration', 4.0)), 5.0)  # Max 5 seconds

        # Get the recording
        recording = db.session.get(Recording, recording_id)
        if not recording:
            return jsonify(api_error('recording_not_found')), 404

        if not has_recording_access(recording, current_user, require_edit=False):
            return jsonify(api_error('recording_access_denied')), 403

        if recording.audio_deleted_at:
            return jsonify(api_error('audio_deleted')), 410

        from src.services.storage import get_storage_service
        storage = get_storage_service()
        if not recording.audio_path or not storage.exists(recording.audio_path):
            return jsonify(api_error('audio_file_not_found')), 404

        try:
            with storage.materialize(recording.audio_path) as materialized:
                # Detect audio codec to pick the right output container for stream copy
                codec_to_container = {
                    'mp3': ('.mp3', 'audio/mpeg'),
                    'aac': ('.m4a', 'audio/mp4'),
                    'opus': ('.ogg', 'audio/ogg'),
                    'vorbis': ('.ogg', 'audio/ogg'),
                    'flac': ('.flac', 'audio/flac'),
                    'pcm_s16le': ('.wav', 'audio/wav'),
                    'pcm_s24le': ('.wav', 'audio/wav'),
                    'pcm_s32le': ('.wav', 'audio/wav'),
                    'pcm_f32le': ('.wav', 'audio/wav'),
                }
                snippet_ext = '.mp3'
                snippet_mime = 'audio/mpeg'
                try:
                    codec_info = get_codec_info(materialized.local_path, timeout=10)
                    audio_codec = codec_info.get('audio_codec')
                    if audio_codec and audio_codec in codec_to_container:
                        snippet_ext, snippet_mime = codec_to_container[audio_codec]
                except FFProbeError:
                    pass  # Fall back to mp3

                # Create temporary file for the snippet
                with tempfile.NamedTemporaryFile(delete=False, suffix=snippet_ext) as tmp_file:
                    output_path = tmp_file.name

                # Use centralized FFmpeg utility to extract the audio segment
                extract_audio_segment(
                    materialized.local_path,
                    output_path,
                    start_time,
                    duration
                )

            # Send the file
            response = send_file(
                output_path,
                mimetype=snippet_mime,
                as_attachment=False,
                download_name=f'snippet_{recording_id}_{start_time:.1f}s{snippet_ext}'
            )

            # Clean up temporary file after sending
            @response.call_on_close
            def cleanup():
                try:
                    os.unlink(output_path)
                except:
                    pass

            return response

        except FFmpegNotFoundError as e:
            current_app.logger.error(f"FFmpeg not found: {e}")
            try:
                os.unlink(output_path)
            except:
                pass
            return jsonify(api_error('ffmpeg_missing')), 500
        except FFmpegError as e:
            current_app.logger.error(f"FFmpeg error extracting snippet: {e}")
            try:
                os.unlink(output_path)
            except:
                pass
            return jsonify(api_error('snippet_extraction_failed')), 500

    except ValueError:
        return jsonify(api_error('invalid_snippet_range')), 400
    except Exception as e:
        current_app.logger.error(f"Error serving audio snippet: {e}")
        return jsonify({'error': str(e)}), 500


@speakers_bp.route('/speakers/merge', methods=['POST'])
@login_required
def merge_speaker_profiles():
    """
    Merge multiple speaker profiles into one.

    Request body:
        {
            'target_id': 5,  # Speaker to keep
            'source_ids': [6, 7, 8],  # Speakers to merge into target
            'preview': false  # Optional: if true, just preview without executing
        }

    Returns merged speaker data or preview statistics.
    """
    try:
        data = request.json
        target_id = data.get('target_id')
        source_ids = data.get('source_ids', [])
        preview = data.get('preview', False)

        if not target_id:
            return jsonify(api_error('target_id_required')), 400

        if not source_ids or not isinstance(source_ids, list):
            return jsonify(api_error('invalid_source_ids')), 400

        # Validate speakers can be merged
        can_merge, error_code = can_merge_speakers([target_id] + source_ids, current_user.id)
        if not can_merge:
            return jsonify(api_error(error_code)), 400

        if preview:
            # Just return preview statistics
            preview_data = preview_merge(target_id, source_ids, current_user.id)
            return jsonify({
                'success': True,
                'preview': preview_data
            })
        else:
            # Execute the merge
            merged_speaker = merge_speakers(target_id, source_ids, current_user.id)
            return jsonify({
                'success': True,
                'message': translate('server.apiMessage.speakersMerged',
                                     count=len(source_ids), name=merged_speaker.name),
                'speaker': merged_speaker.to_dict(),
                'recordings_updated': getattr(merged_speaker, 'recordings_updated', 0)
            })

    except ValueError as e:
        return jsonify({'error': str(e)}), 400
    except Exception as e:
        db.session.rollback()
        current_app.logger.error(f"Error merging speakers: {e}")
        return jsonify({'error': str(e)}), 500