Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
Document DELETE_ORPHANED_SPEAKERS and update speaker cleanup docs
Murtaza Nasirdf0bc870fe80
diff --git a/README.md b/README.mdindex 388eeafe..5bf7eb2d 100644--- a/README.md+++ b/README.md@@ -169,6 +169,7 @@ Complete documentation is available at **[murtaza-nasir.github.io/speakr](https:- **Video Retention** - New `VIDEO_RETENTION=true` option preserves video streams for in-browser playback. When enabled, uploaded video files keep their video track and render with a native `<video>` player alongside the transcript. Audio is extracted to a temp file for transcription and cleaned up automatically. HTTP Range requests enable seeking without downloading the full file.- **Parallel Uploads** - Multiple files upload concurrently with individual progress bars, making batch uploads significantly faster. Configurable via `MAX_CONCURRENT_UPLOADS` (default: 3)- **Duplicate Detection** - SHA-256 file hashing detects duplicate uploads with warning toasts and a clickable copies indicator in the sidebar and header+- **Speaker Profile Preservation** - Speaker profiles and voice embeddings are now preserved by default when all recordings are deleted. Set `DELETE_ORPHANED_SPEAKERS=true` to enable automatic cleanup- **Volume Controls** - Volume slider popups and mute visual indicators on all audio/video players- **Speaker Enhancements** - Split button UI, apply suggested names, name sanitization, JSON schema option, new speaker API endpoints- **Localization** - Complete translations for folders, API tokens, recording recovery, events, and speakers managementdiff --git a/docs/admin-guide/retention.md b/docs/admin-guide/retention.mdindex 8080c698..115764a5 100644--- a/docs/admin-guide/retention.md+++ b/docs/admin-guide/retention.md@@ -164,13 +164,15 @@ GET /admin/auto-deletion/stats## Speaker Data Cleanup-When recordings are automatically deleted, Speakr manages associated speaker voice profile data to maintain privacy and GDPR compliance.+By default, speaker profiles and voice embeddings are preserved even when all associated recordings are deleted. This is because voice embeddings are aggregated values that cannot be reconstructed from individual recordings.++To enable automatic cleanup of orphaned speaker profiles, set `DELETE_ORPHANED_SPEAKERS=true` in your environment.### What Gets Cleaned Up-When the auto-deletion job runs, the system automatically:+When `DELETE_ORPHANED_SPEAKERS=true` and the auto-deletion job runs, the system:-1. **Removes orphaned speaker profiles**: Speakers with no remaining recordings are deleted entirely+1. **Removes orphaned speaker profiles**: Speakers with no remaining recordings are deleted2. **Cleans embedding references**: Recording IDs are removed from speaker voice profile metadata3. **Applies to both deletion modes**: Works with both `audio_only` and `full_recording` deletion modes@@ -179,29 +181,26 @@ When the auto-deletion job runs, the system automatically:Speaker cleanup runs on the same schedule as auto-deletion:- **Frequency**: Daily at 2:00 AM (server time)-- **Trigger**: Automatically when `ENABLE_AUTO_DELETION=true`-- **No additional configuration**: Uses existing auto-deletion settings+- **Trigger**: Automatically when `ENABLE_AUTO_DELETION=true` and `DELETE_ORPHANED_SPEAKERS=true`### When Speakers Are DeletedA speaker is considered "orphaned" and deleted when:+- `DELETE_ORPHANED_SPEAKERS=true` is set- No `SpeakerSnippet` records exist for the speaker (no voice samples in any recordings)- No valid recording references remain in the speaker's voice profile metadata-- This occurs after all recordings containing that speaker have been deleted**Note**: Speakers are preserved as long as they have at least one active recording with speaker identifications.### Privacy & GDPR Compliance-This automatic cleanup ensures:+For deployments that need to treat voice embeddings as biometric data, enable `DELETE_ORPHANED_SPEAKERS=true` to ensure:-- **Data Minimization**: Removes biometric voice data (embeddings) when no longer needed for system function-- **Right to Erasure**: Deletes personal data (voice profiles) when recordings are removed+- **Data Minimization**: Removes voice data when no longer needed+- **Right to Erasure**: Deletes voice profiles when recordings are removed- **Transparency**: Cleanup activity is logged for audit purposes-- **No Manual Action Required**: Cleanup happens automatically with retention policies--The system treats voice embeddings as biometric data under GDPR. When recordings are deleted (either through auto-deletion or manual deletion), the associated voice profile data is evaluated for removal. This ensures compliance with data protection regulations without requiring manual intervention.+- **Automatic**: No manual intervention required when combined with retention policies### Monitoring Cleanup Activitydiff --git a/docs/admin-guide/system-settings.md b/docs/admin-guide/system-settings.mdindex 055028f9..4d106068 100644--- a/docs/admin-guide/system-settings.md+++ b/docs/admin-guide/system-settings.md@@ -125,6 +125,10 @@ Jobs are persisted to the database and survive application restarts. If Speakr r**SKIP_EMAIL_DOMAIN_CHECK**: When `true`, bypasses DNS validation of email domains when creating admin users via the setup script. Useful for development or when DNS lookups are restricted. Default: `false`.+### Speaker Profile Cleanup++**DELETE_ORPHANED_SPEAKERS**: Controls whether speaker profiles are automatically deleted when all their associated recordings are removed. When `false` (the default), speaker profiles and voice embeddings are preserved. When `true`, speakers with no remaining recordings are automatically cleaned up. Default: `false`.+### Video Retention**VIDEO_RETENTION**: When enabled, uploaded video files keep their video stream for in-browser playback instead of extracting audio and discarding the video. The audio is extracted to a temporary file for transcription only, then cleaned up after processing. The video renders with a native `<video>` player alongside the transcript, with full seeking support via HTTP Range requests. All player controls (play/pause, seek, speed, volume) work identically. Ideal for presentations, lectures, and screen recordings. Default: `false`.@@ -170,6 +174,9 @@ AUDIO_COMPRESS_UPLOADS=trueAUDIO_CODEC=mp3AUDIO_BITRATE=128k+# Speaker cleanup (preserve profiles by default)+DELETE_ORPHANED_SPEAKERS=false+# Video retention (keep video files for playback)VIDEO_RETENTION=falsediff --git a/docs/features.md b/docs/features.mdindex e746bd45..f14dccd0 100644--- a/docs/features.md+++ b/docs/features.md@@ -104,7 +104,7 @@ Build and maintain a library of speaker profiles that persist across recordings.**Auto Speaker Labeling**: Enable automatic speaker identification in your [account settings](user-guide/settings.md#processing-preferences). When enabled, new recordings are automatically analyzed against your speaker profiles, and matching speakers are labeled without manual intervention. Configure the confidence threshold to balance between more matches (low threshold) and higher accuracy (high threshold). This feature requires WhisperX ASR with speaker embeddings enabled.-**Privacy-First Cleanup**: Voice profiles are automatically managed alongside recording retention policies. When all recordings containing a particular speaker are deleted, the speaker's voice profile is automatically removed during the next scheduled cleanup. This ensures biometric voice data is only retained when actively used, maintaining compliance with data minimization principles. The cleanup process is fully automatic and requires no manual intervention when auto-deletion is enabled.+**Speaker Profile Preservation**: By default, speaker profiles and voice embeddings are preserved even when all associated recordings are deleted. Set `DELETE_ORPHANED_SPEAKERS=true` to automatically clean up speakers with no remaining recordings.### Custom Promptsdiff --git a/docs/user-guide/settings.md b/docs/user-guide/settings.mdindex 5f3a775f..cc210ccc 100644--- a/docs/user-guide/settings.md+++ b/docs/user-guide/settings.md@@ -148,12 +148,9 @@ Regular maintenance keeps your speaker library relevant. Remove speakers who noWhen recordings are deleted (either manually or through auto-deletion), Speakr automatically manages speaker voice profiles to protect your privacy:- **Speakers with remaining recordings**: Voice profiles are preserved and continue to provide recognition suggestions-- **Speakers with no recordings**: Automatically removed during the next scheduled cleanup to ensure voice data is not retained unnecessarily-- **No manual action needed**: Cleanup happens automatically when auto-deletion is enabled+- **Speakers with no recordings**: Preserved by default. If `DELETE_ORPHANED_SPEAKERS=true` is set, they are automatically removed during the next scheduled cleanup-This automatic cleanup ensures your speaker list stays current and maintains compliance with data privacy regulations. Voice embeddings (biometric data) are only retained when there are active recordings that reference the speaker, following data minimization principles.--**Note**: If you want to preserve a speaker's voice profile, ensure at least one recording containing that speaker is retained. Protected recordings (with protected tags) will preserve their associated speakers.+**Note**: Protected recordings (with protected tags) will always preserve their associated speakers.## Tag Management Tab