Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
Add separate queues for transcription and summary jobs
Murtaza Nasir922efa03105a
diff --git a/config/env.asr.example b/config/env.asr.exampleindex 1ee3405d..00f15f0a 100644--- a/config/env.asr.example+++ b/config/env.asr.example@@ -138,11 +138,16 @@ ENABLE_PUBLIC_SHARING=true# Note: Admins can control public sharing permissions per-user in the admin dashboard# even when ENABLE_PUBLIC_SHARING is true-# --- Background Processing Queue ----# Number of concurrent workers for processing uploads (default: 2)-# Increase for higher throughput, decrease to limit resource usage+# --- Background Processing Queues ---+# Separate queues for transcription (slow) and summary (fast) jobs+# This prevents slow ASR jobs from blocking quick summary generation++# Transcription queue workers (for ASR processing, default: 2)JOB_QUEUE_WORKERS=2+# Summary queue workers (for LLM summarization, default: 2)+SUMMARY_QUEUE_WORKERS=2+# Maximum retry attempts for failed jobs (default: 3)JOB_MAX_RETRIES=3diff --git a/config/env.whisper.example b/config/env.whisper.exampleindex c3eb5357..db1d1dfb 100644--- a/config/env.whisper.example+++ b/config/env.whisper.example@@ -141,11 +141,16 @@ ENABLE_PUBLIC_SHARING=true# Note: Admins can control public sharing permissions per-user in the admin dashboard# even when ENABLE_PUBLIC_SHARING is true-# --- Background Processing Queue ----# Number of concurrent workers for processing uploads (default: 2)-# Increase for higher throughput, decrease to limit resource usage+# --- Background Processing Queues ---+# Separate queues for transcription (slow) and summary (fast) jobs+# This prevents slow ASR jobs from blocking quick summary generation++# Transcription queue workers (for ASR processing, default: 2)JOB_QUEUE_WORKERS=2+# Summary queue workers (for LLM summarization, default: 2)+SUMMARY_QUEUE_WORKERS=2+# Maximum retry attempts for failed jobs (default: 3)JOB_MAX_RETRIES=3diff --git a/config/env.whisperx.example b/config/env.whisperx.exampleindex f9097d39..af830353 100644--- a/config/env.whisperx.example+++ b/config/env.whisperx.example@@ -148,11 +148,16 @@ ENABLE_PUBLIC_SHARING=true# Note: Admins can control public sharing permissions per-user in the admin dashboard# even when ENABLE_PUBLIC_SHARING is true-# --- Background Processing Queue ----# Number of concurrent workers for processing uploads (default: 2)-# Increase for higher throughput, decrease to limit resource usage+# --- Background Processing Queues ---+# Separate queues for transcription (slow) and summary (fast) jobs+# This prevents slow ASR jobs from blocking quick summary generation++# Transcription queue workers (for ASR processing, default: 2)JOB_QUEUE_WORKERS=2+# Summary queue workers (for LLM summarization, default: 2)+SUMMARY_QUEUE_WORKERS=2+# Maximum retry attempts for failed jobs (default: 3)JOB_MAX_RETRIES=3diff --git a/docs/admin-guide/system-settings.md b/docs/admin-guide/system-settings.mdindex 4381130b..aad93f96 100644--- a/docs/admin-guide/system-settings.md+++ b/docs/admin-guide/system-settings.md@@ -78,11 +78,13 @@ Beyond the UI-configurable settings above, several environment variables in yourFor detailed retention configuration, see the [Retention & Auto-Deletion](retention.md) guide.-### Background Processing Queue+### Background Processing Queues-Speakr uses a fair job queue to process uploads and reprocessing requests. The queue ensures multiple users get fair access to processing resources.+Speakr uses separate job queues for transcription and summarization to prevent slow ASR processing from blocking quick summary generation.-**JOB_QUEUE_WORKERS**: Number of concurrent workers processing jobs. Higher values increase throughput but consume more resources. Default: `2`.+**JOB_QUEUE_WORKERS**: Number of workers for transcription jobs (ASR processing). These are slow jobs that can take 5-30 minutes. Default: `2`.++**SUMMARY_QUEUE_WORKERS**: Number of workers for summary jobs (LLM API calls). These are fast jobs that typically complete in under a minute. Default: `2`.**JOB_MAX_RETRIES**: How many times a failed job will be retried before being marked as failed. Default: `3`.diff --git a/src/config/startup.py b/src/config/startup.pyindex 91f45b53..2d4f0724 100644--- a/src/config/startup.py+++ b/src/config/startup.py@@ -124,7 +124,13 @@ def initialize_job_queue(app):# Get queue statusstatus = job_queue.get_queue_status()- app.logger.info(f"Job queue started with {status['num_workers']} workers, {status['queued_jobs']} queued jobs")+ t_queue = status['transcription_queue']+ s_queue = status['summary_queue']+ app.logger.info(+ f"Job queues started: "+ f"transcription ({t_queue['workers']} workers, {t_queue['queued']} queued), "+ f"summary ({s_queue['workers']} workers, {s_queue['queued']} queued)"+ )except Exception as e:app.logger.error(f"Failed to start job queue: {e}", exc_info=True)diff --git a/src/services/job_queue.py b/src/services/job_queue.pyindex 7a61fac8..6f884fd1 100644--- a/src/services/job_queue.py+++ b/src/services/job_queue.py@@ -4,6 +4,7 @@ Fair database-backed job queue for background processing tasks.This queue ensures:- Jobs persist across application restarts- Fair round-robin scheduling between users+- Separate queues for transcription (slow) and summary (fast) jobs- Limited concurrency to prevent overwhelming external services- Automatic recovery of orphaned jobs"""@@ -14,51 +15,57 @@ import threadingimport timeimport loggingfrom datetime import datetime-from typing import Optional, Dict, Any, Callable+from typing import Optional, Dict, Any, Listfrom contextlib import contextmanagerlogger = logging.getLogger(__name__)# Configuration-MAX_WORKERS = int(os.environ.get('JOB_QUEUE_WORKERS', '2'))+TRANSCRIPTION_WORKERS = int(os.environ.get('JOB_QUEUE_WORKERS', '2'))+SUMMARY_WORKERS = int(os.environ.get('SUMMARY_QUEUE_WORKERS', '2'))MAX_RETRIES = int(os.environ.get('JOB_MAX_RETRIES', '3'))POLL_INTERVAL = 1.0 # seconds between checking for new jobs+# Job type categories+TRANSCRIPTION_JOBS = ['transcribe', 'reprocess_transcription']+SUMMARY_JOBS = ['summarize', 'reprocess_summary']+class FairJobQueue:"""A database-backed job queue with fair scheduling across users.- Uses round-robin scheduling to ensure all users get fair processing time,- preventing one user from monopolizing the queue.+ Uses separate queues for transcription and summary jobs to prevent+ slow transcription jobs from blocking fast summary jobs."""_instance = None_lock = threading.Lock()- def __new__(cls, num_workers: int = None):+ def __new__(cls):"""Singleton pattern to ensure only one queue exists."""if cls._instance is None:with cls._lock:if cls._instance is None:cls._instance = super().__new__(cls)cls._instance._initialized = False- cls._instance._num_workers_init = num_workers or MAX_WORKERSreturn cls._instance- def __init__(self, num_workers: int = None):+ def __init__(self):"""Initialize the job queue."""if self._initialized:return- self._num_workers = getattr(self, '_num_workers_init', num_workers or MAX_WORKERS)- self._workers = []+ self._transcription_workers = []+ self._summary_workers = []self._running = Falseself._app = None- self._last_user_id = None # For round-robin tracking+ # Separate round-robin tracking for each queue+ self._last_user_id_transcription = None+ self._last_user_id_summary = Noneself._initialized = True- logger.info(f"FairJobQueue initialized with {self._num_workers} workers")+ logger.info(f"FairJobQueue initialized: {TRANSCRIPTION_WORKERS} transcription workers, {SUMMARY_WORKERS} summary workers")def init_app(self, app):"""Initialize with Flask app for context management."""@@ -74,47 +81,66 @@ class FairJobQueue:yielddef start(self):- """Start the worker threads."""+ """Start the worker threads for both queues."""if self._running:returnself._running = True- for i in range(self._num_workers):++ # Start transcription workers+ for i in range(TRANSCRIPTION_WORKERS):+ worker = threading.Thread(+ target=self._worker_loop,+ args=(TRANSCRIPTION_JOBS, 'transcription'),+ name=f"TranscriptionWorker-{i}",+ daemon=True+ )+ worker.start()+ self._transcription_workers.append(worker)++ # Start summary workers+ for i in range(SUMMARY_WORKERS):worker = threading.Thread(target=self._worker_loop,- name=f"FairJobQueueWorker-{i}",+ args=(SUMMARY_JOBS, 'summary'),+ name=f"SummaryWorker-{i}",daemon=True)worker.start()- self._workers.append(worker)+ self._summary_workers.append(worker)- logger.info(f"Started {self._num_workers} fair job queue workers")+ logger.info(f"Started {TRANSCRIPTION_WORKERS} transcription workers and {SUMMARY_WORKERS} summary workers")def stop(self):"""Stop the worker threads gracefully."""self._running = False- for worker in self._workers:+ for worker in self._transcription_workers + self._summary_workers:worker.join(timeout=5)- self._workers.clear()- logger.info("Fair job queue workers stopped")+ self._transcription_workers.clear()+ self._summary_workers.clear()+ logger.info("Job queue workers stopped")- def _worker_loop(self):- """Main worker loop that processes jobs from the database."""+ def _worker_loop(self, job_types: List[str], queue_name: str):+ """Main worker loop that processes jobs of specific types."""while self._running:try:- job = self._claim_next_job()+ job = self._claim_next_job(job_types, queue_name)if job:self._process_job(job)else:# No jobs available, sleep brieflytime.sleep(POLL_INTERVAL)except Exception as e:- logger.error(f"Worker error: {e}", exc_info=True)+ logger.error(f"{queue_name.capitalize()} worker error: {e}", exc_info=True)time.sleep(POLL_INTERVAL)- def _claim_next_job(self):+ def _claim_next_job(self, job_types: List[str], queue_name: str):"""- Claim the next job using fair round-robin scheduling.+ Claim the next job of specified types using fair round-robin scheduling.++ Args:+ job_types: List of job types this worker handles+ queue_name: Name of the queue ('transcription' or 'summary')Returns the claimed job or None if no jobs available."""@@ -123,11 +149,12 @@ class FairJobQueue:from src.models import ProcessingJobtry:- # Get list of users with queued jobs, ordered by oldest job first+ # Get list of users with queued jobs of our typesusers_with_jobs = db.session.query(ProcessingJob.user_id).filter(- ProcessingJob.status == 'queued'+ ProcessingJob.status == 'queued',+ ProcessingJob.job_type.in_(job_types)).group_by(ProcessingJob.user_id).order_by(@@ -139,18 +166,24 @@ class FairJobQueue:user_ids = [u[0] for u in users_with_jobs]+ # Get last user ID for this queue type+ last_user_id = (self._last_user_id_transcription+ if queue_name == 'transcription'+ else self._last_user_id_summary)+# Round-robin: pick next user after last processednext_user_id = None- if self._last_user_id is not None and self._last_user_id in user_ids:- idx = user_ids.index(self._last_user_id)+ if last_user_id is not None and last_user_id in user_ids:+ idx = user_ids.index(last_user_id)next_user_id = user_ids[(idx + 1) % len(user_ids)]else:next_user_id = user_ids[0]- # Get oldest queued job for this user+ # Get oldest queued job of our types for this userjob = ProcessingJob.query.filter(ProcessingJob.user_id == next_user_id,- ProcessingJob.status == 'queued'+ ProcessingJob.status == 'queued',+ ProcessingJob.job_type.in_(job_types)).order_by(ProcessingJob.created_at).with_for_update(skip_locked=True).first()@@ -160,16 +193,21 @@ class FairJobQueue:job.status = 'processing'job.started_at = datetime.utcnow()db.session.commit()- self._last_user_id = next_user_id++ # Update last user ID for this queue+ if queue_name == 'transcription':+ self._last_user_id_transcription = next_user_id+ else:+ self._last_user_id_summary = next_user_idwait_time = (datetime.utcnow() - job.created_at).total_seconds()- logger.info(f"Claimed job {job.id} (type={job.job_type}) for user {job.user_id}, recording {job.recording_id} (waited {wait_time:.1f}s)")+ logger.info(f"[{queue_name.upper()}] Claimed job {job.id} (type={job.job_type}) for user {job.user_id}, recording {job.recording_id} (waited {wait_time:.1f}s)")return jobreturn Noneexcept Exception as e:- logger.error(f"Error claiming job: {e}", exc_info=True)+ logger.error(f"Error claiming {queue_name} job: {e}", exc_info=True)db.session.rollback()return None@@ -319,14 +357,16 @@ class FairJobQueue:from src.database import dbfrom src.models import ProcessingJob, Recording- # Check for existing active job for this recording+ # Check for existing active job of the SAME TYPE for this recording+ # Allow different job types to coexist (e.g., transcribe and summarize)existing = ProcessingJob.query.filter(ProcessingJob.recording_id == recording_id,+ ProcessingJob.job_type == job_type,ProcessingJob.status.in_(['queued', 'processing'])).first()if existing:- logger.warning(f"Job already exists for recording {recording_id}: {existing.id}")+ logger.warning(f"Job of type {job_type} already exists for recording {recording_id}: {existing.id}")return existing.id# Create new job@@ -338,10 +378,13 @@ class FairJobQueue:)db.session.add(job)- # Update recording status to QUEUED+ # Update recording status based on job typerecording = db.session.get(Recording, recording_id)if recording:- recording.status = 'QUEUED'+ if job_type in SUMMARY_JOBS:+ recording.status = 'SUMMARIZING'+ else:+ recording.status = 'QUEUED'db.session.commit()@@ -349,7 +392,8 @@ class FairJobQueue:if not self._running:self.start()- logger.info(f"Enqueued job {job.id} (type={job_type}) for user {user_id}, recording {recording_id}")+ queue_name = 'summary' if job_type in SUMMARY_JOBS else 'transcription'+ logger.info(f"Enqueued {queue_name} job {job.id} (type={job_type}) for user {user_id}, recording {recording_id}")return job.iddef recover_orphaned_jobs(self):@@ -368,29 +412,52 @@ class FairJobQueue:for job in orphaned:job.status = 'queued'job.started_at = None- logger.info(f"Recovered orphaned job {job.id} for recording {job.recording_id}")+ queue_name = 'summary' if job.job_type in SUMMARY_JOBS else 'transcription'+ logger.info(f"Recovered orphaned {queue_name} job {job.id} for recording {job.recording_id}")if orphaned:db.session.commit()logger.info(f"Recovered {len(orphaned)} orphaned jobs")def get_queue_status(self) -> Dict[str, Any]:- """Get the current queue status."""+ """Get the current queue status for both queues."""with self._app_context():from src.models import ProcessingJob- queued = ProcessingJob.query.filter_by(status='queued').count()- processing = ProcessingJob.query.filter_by(status='processing').count()+ transcription_queued = ProcessingJob.query.filter(+ ProcessingJob.status == 'queued',+ ProcessingJob.job_type.in_(TRANSCRIPTION_JOBS)+ ).count()+ transcription_processing = ProcessingJob.query.filter(+ ProcessingJob.status == 'processing',+ ProcessingJob.job_type.in_(TRANSCRIPTION_JOBS)+ ).count()++ summary_queued = ProcessingJob.query.filter(+ ProcessingJob.status == 'queued',+ ProcessingJob.job_type.in_(SUMMARY_JOBS)+ ).count()+ summary_processing = ProcessingJob.query.filter(+ ProcessingJob.status == 'processing',+ ProcessingJob.job_type.in_(SUMMARY_JOBS)+ ).count()return {- "queued_jobs": queued,- "processing_jobs": processing,- "num_workers": self._num_workers,+ "transcription_queue": {+ "queued": transcription_queued,+ "processing": transcription_processing,+ "workers": TRANSCRIPTION_WORKERS+ },+ "summary_queue": {+ "queued": summary_queued,+ "processing": summary_processing,+ "workers": SUMMARY_WORKERS+ },"is_running": self._running}def get_position_in_queue(self, recording_id: int) -> Optional[int]:- """Get the position of a recording's job in the queue (1-indexed)."""+ """Get the position of a recording's job in its respective queue (1-indexed)."""with self._app_context():from src.models import ProcessingJob@@ -402,9 +469,13 @@ class FairJobQueue:if not job:return None- # Count jobs created before this one+ # Determine which queue this job is in+ job_types = SUMMARY_JOBS if job.job_type in SUMMARY_JOBS else TRANSCRIPTION_JOBS++ # Count jobs of the same type created before this oneposition = ProcessingJob.query.filter(ProcessingJob.status == 'queued',+ ProcessingJob.job_type.in_(job_types),ProcessingJob.created_at < job.created_at).count() + 1