Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
"""
Speaker Merge Service.
This service handles merging multiple speaker profiles into one.
Useful when users accidentally create duplicate speakers for the same person.
When speakers are merged:
- Voice embeddings are combined using weighted average
- All snippets are transferred to the target speaker
- Usage statistics are combined
- Every recording that shows a source speaker's name shows the target's name
- Source speakers are deleted
- Confidence score is recalculated
"""
import json
import numpy as np
from src.database import db
from src.models import Speaker, SpeakerSnippet
from src.services.speaker_embedding_matcher import (
serialize_embedding,
deserialize_embedding,
calculate_confidence
)
def merge_speakers(target_id, source_ids, user_id):
"""
Merge multiple speaker profiles into one target speaker.
All embeddings, snippets, and usage data from source speakers are
combined into the target speaker. Source speakers are then deleted.
Args:
target_id: ID of the speaker to keep (receives all merged data)
source_ids: List of speaker IDs to merge into target
user_id: ID of the user (for security check)
Returns:
Speaker: The updated target speaker
Raises:
ValueError: If speakers don't exist or don't belong to user
"""
# Validate target speaker
target = Speaker.query.filter_by(id=target_id, user_id=user_id).first()
if not target:
raise ValueError(f"Target speaker {target_id} not found or doesn't belong to user")
# Validate source speakers
sources = Speaker.query.filter(
Speaker.id.in_(source_ids),
Speaker.user_id == user_id
).all()
if len(sources) == 0:
raise ValueError("No valid source speakers found")
if len(sources) != len(source_ids):
raise ValueError("Some source speakers don't exist or don't belong to user")
# Can't merge a speaker with itself
if target_id in source_ids:
raise ValueError("Cannot merge a speaker with itself")
# Move the voice samples. The target's variants are rebuilt from the
# combined samples below, so the merge keeps every voice condition the
# people had instead of averaging them into one vector.
_merge_voice_samples(target, sources)
# Transfer snippets
for source in sources:
SpeakerSnippet.query.filter_by(speaker_id=source.id).update(
{'speaker_id': target_id}
)
# Combine usage statistics
for source in sources:
target.use_count += source.use_count
# Update last_used to most recent
if source.last_used and (not target.last_used or source.last_used > target.last_used):
target.last_used = source.last_used
# Combine embedding histories
if source.embeddings_history:
target_history = target.embeddings_history or []
source_history = source.embeddings_history or []
combined_history = target_history + source_history
# Sort by timestamp (most recent last) and keep last 10
try:
combined_history.sort(key=lambda x: x.get('timestamp', ''))
target.embeddings_history = combined_history[-10:]
except:
# If sorting fails, just concatenate and truncate
target.embeddings_history = (target_history + source_history)[-10:]
# Summary columns (average, count, history, confidence) from the samples
from src.services.voice_profiles import refresh_speaker_summary
db.session.flush()
refresh_speaker_summary(target)
# Recordings keep speaker names, not speaker ids: without this the
# recordings of a merged speaker kept showing the old name.
renamed = {}
for source in sources:
_, changed = rename_speaker_in_recordings(user_id, source.name, target.name,
speaker_id=source.id, new_speaker_id=target.id)
for rid, fields in changed.items():
renamed.setdefault(rid, set()).update(fields)
target.recordings_updated = len(renamed) # for the route's answer, not a column
# Delete source speakers
for source in sources:
db.session.delete(source)
# Commit all changes
db.session.commit()
refresh_renamed_recordings(renamed)
return target
def _same_name(a, b):
return isinstance(a, str) and a.strip().lower() == b.strip().lower()
def rename_speaker_in_recordings(user_id, old_name, new_name, speaker_id=None, new_speaker_id=None):
"""Show new_name wherever the user's recordings show old_name.
Covers the transcript segments, the participants list, the diarization
label map and the Inquire chunks' speaker column. A segment linked to
speaker_id follows the link (and is linked to new_speaker_id); a segment
without a link matches by name, ignoring case and surrounding spaces, as
saved speakers do. Does not commit.
Returns (chunks_updated, {recording id: set of the fields changed}).
"""
from src.models import Recording, TranscriptChunk
old_key = old_name.strip().lower()
chunks_updated = 0
for chunk in TranscriptChunk.query.filter(
TranscriptChunk.user_id == user_id,
db.func.lower(db.func.trim(TranscriptChunk.speaker_name)) == old_key).all():
chunk.speaker_name = new_name
chunks_updated += 1
changed = {}
for recording in Recording.query.filter_by(user_id=user_id).all():
fields = set()
if recording.participants:
names = [p.strip() for p in recording.participants.split(',') if p.strip()]
if any(_same_name(p, old_name) for p in names):
merged = []
for p in names:
p = new_name if _same_name(p, old_name) else p
if not any(_same_name(p, m) for m in merged):
merged.append(p)
recording.participants = ', '.join(merged)
fields.add('participants')
if recording.transcription:
try:
segments = json.loads(recording.transcription)
except (json.JSONDecodeError, TypeError):
segments = None
if isinstance(segments, list):
hit = False
for segment in segments:
if not isinstance(segment, dict):
continue
linked = segment.get('speaker_id')
if (speaker_id is not None and linked == speaker_id) or \
(linked is None and _same_name(segment.get('speaker'), old_name)):
if segment.get('speaker') != new_name:
segment['speaker'] = new_name
hit = True
if new_speaker_id is not None and linked != new_speaker_id:
segment['speaker_id'] = new_speaker_id
hit = True
if hit:
recording.transcription = json.dumps(segments)
fields.add('transcription')
# The label map records which name each diarization label shows;
# without this the next save would think the voice was removed.
label_map = recording.speaker_label_map
if isinstance(label_map, dict) and any(_same_name(n, old_name) for n in label_map.values()):
recording.speaker_label_map = {
label: (new_name if _same_name(n, old_name) else n) for label, n in label_map.items()}
fields.add('speaker_label_map')
if fields:
changed.setdefault(recording.id, set()).update(fields)
return chunks_updated, changed
def refresh_renamed_recordings(changed):
"""After names change in committed recordings: rebuild their Inquire
chunks (the chunk text holds the names), rewrite their auto-exports and
recording.updated goes out from the change listener on commit.
changed: {recording id: fields}."""
if not changed:
return
from flask import current_app
from src.api import recordings as recordings_api
from src.file_exporter import ENABLE_AUTO_EXPORT, export_recording
for rid in sorted(changed):
recordings_api.reindex_recording_chunks_async(rid)
if ENABLE_AUTO_EXPORT:
try:
export_recording(rid)
except Exception as e:
current_app.logger.warning(f"Export after speaker rename failed for {rid}: {e}")
def _merge_voice_samples(target, sources):
"""Give the target every voice sample of the sources.
Profiles from before samples existed are written out as samples first,
so nothing they learned is lost.
"""
from src.models import SpeakerVoiceSample
from src.services.voice_profiles import _materialize_legacy
for speaker in [target] + list(sources):
_materialize_legacy(speaker)
for source in sources:
SpeakerVoiceSample.query.filter_by(speaker_id=source.id).update({'speaker_id': target.id})
db.session.flush()
def _combine_embeddings(target, sources):
"""
Combine embeddings from multiple speakers using weighted average.
Weight is based on embedding_count (more samples = more weight).
Args:
target: Target Speaker instance
sources: List of source Speaker instances
"""
all_embeddings = []
all_counts = []
# Add target's embedding if it exists
if target.average_embedding:
all_embeddings.append(deserialize_embedding(target.average_embedding))
all_counts.append(target.embedding_count or 1)
# Add all source embeddings
for source in sources:
if source.average_embedding:
all_embeddings.append(deserialize_embedding(source.average_embedding))
all_counts.append(source.embedding_count or 1)
if not all_embeddings:
# No embeddings to combine
return
# Calculate weighted average
total_count = sum(all_counts)
weights = [c / total_count for c in all_counts]
combined_emb = np.average(all_embeddings, axis=0, weights=weights)
# Update target
target.average_embedding = serialize_embedding(combined_emb)
target.embedding_count = total_count
def preview_merge(target_id, source_ids, user_id):
"""
Preview what a merge would look like without executing it.
Args:
target_id: ID of the target speaker
source_ids: List of source speaker IDs
user_id: ID of the user
Returns:
dict: Preview of the merge results
{
'target_name': '...',
'source_names': [...],
'combined_use_count': 123,
'combined_embedding_count': 45,
'total_snippets': 67
}
"""
# Validate speakers
target = Speaker.query.filter_by(id=target_id, user_id=user_id).first()
if not target:
raise ValueError("Target speaker not found")
sources = Speaker.query.filter(
Speaker.id.in_(source_ids),
Speaker.user_id == user_id
).all()
if len(sources) == 0:
raise ValueError("No valid source speakers found")
# Calculate combined statistics
combined_use_count = target.use_count
combined_embedding_count = target.embedding_count or 0
total_snippets = SpeakerSnippet.query.filter_by(speaker_id=target_id).count()
source_names = []
for source in sources:
combined_use_count += source.use_count
combined_embedding_count += (source.embedding_count or 0)
total_snippets += SpeakerSnippet.query.filter_by(speaker_id=source.id).count()
source_names.append(source.name)
return {
'target_name': target.name,
'source_names': source_names,
'combined_use_count': combined_use_count,
'combined_embedding_count': combined_embedding_count,
'total_snippets': total_snippets,
'has_embeddings': target.average_embedding is not None or any(s.average_embedding for s in sources)
}
def can_merge_speakers(speaker_ids, user_id):
"""
Check if speakers can be merged (all belong to same user, no duplicates).
Args:
speaker_ids: List of speaker IDs
user_id: ID of the user
Returns:
tuple: (bool, str) - (can_merge, error code): the code is a
server.apiError key (#477), '' when the merge can go ahead
"""
if len(speaker_ids) < 2:
return False, 'merge_needs_two_speakers'
if len(speaker_ids) != len(set(speaker_ids)):
return False, 'duplicate_speaker_ids'
speakers = Speaker.query.filter(
Speaker.id.in_(speaker_ids),
Speaker.user_id == user_id
).all()
if len(speakers) != len(speaker_ids):
return False, 'speakers_not_found_or_not_owned'
return True, ""