Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
"""
Transcription usage tracking service for monitoring audio transcription consumption and budget enforcement.
"""
import logging
from datetime import date, datetime, timedelta
from typing import Tuple, Optional, Dict, List
from sqlalchemy import func, extract
from src.database import db
from src.models.transcription_usage import TranscriptionUsage
from src.models.user import User
from src.utils.localization import format_number, format_percent, translate
logger = logging.getLogger(__name__)
# Pricing configuration per connector/model (dollars per minute)
TRANSCRIPTION_PRICING = {
'openai_whisper': {
'whisper-1': 0.006, # $0.006/min
'default': 0.006,
},
'openai_transcribe': {
'gpt-4o-transcribe': 0.006, # $0.006/min
'gpt-4o-mini-transcribe': 0.003, # $0.003/min
'gpt-4o-mini-transcribe-2025-12-15': 0.003,
'gpt-4o-transcribe-diarize': 0.006,
'default': 0.006,
},
'asr_endpoint': {
'default': 0.0, # Self-hosted = free
},
}
def get_transcription_cost_per_minute(connector_type: str, model_name: str = None) -> float:
"""
Get the cost per minute for a given connector and model.
Args:
connector_type: The connector provider name
model_name: The specific model (optional)
Returns:
Cost per minute in dollars
"""
connector_pricing = TRANSCRIPTION_PRICING.get(connector_type, {})
if model_name and model_name in connector_pricing:
return connector_pricing[model_name]
# Fall back to 'default' pricing for the connector
return connector_pricing.get('default', 0.0)
class TranscriptionTracker:
"""Service for recording and checking transcription usage."""
CONNECTOR_TYPES = [
'openai_whisper',
'openai_transcribe',
'asr_endpoint',
]
def record_usage(
self,
user_id: int,
connector_type: str,
audio_duration_seconds: int,
model_name: str = None,
estimated_cost: float = None
):
"""
Record transcription usage - upserts into daily aggregate.
Args:
user_id: User ID who made the request
connector_type: Type of connector (openai_whisper, openai_transcribe, asr_endpoint)
audio_duration_seconds: Duration of audio transcribed in seconds
model_name: Name of the model used
estimated_cost: Pre-calculated cost (if None, calculated from pricing config)
"""
try:
today = date.today()
# Calculate cost if not provided
if estimated_cost is None:
cost_per_minute = get_transcription_cost_per_minute(connector_type, model_name)
estimated_cost = (audio_duration_seconds / 60.0) * cost_per_minute
# Find or create today's record for this user/connector
usage = TranscriptionUsage.query.filter_by(
user_id=user_id,
date=today,
connector_type=connector_type
).first()
if usage:
# Update existing record
usage.audio_duration_seconds += audio_duration_seconds
usage.estimated_cost += estimated_cost
usage.request_count += 1
if model_name:
usage.model_name = model_name # Update to latest model used
else:
# Create new record
usage = TranscriptionUsage(
user_id=user_id,
date=today,
connector_type=connector_type,
audio_duration_seconds=audio_duration_seconds,
request_count=1,
model_name=model_name,
estimated_cost=estimated_cost or 0.0
)
db.session.add(usage)
db.session.commit()
logger.debug(f"Recorded {audio_duration_seconds}s transcription for user {user_id}, connector {connector_type}")
return usage
except Exception as e:
logger.error(f"Failed to record transcription usage: {e}")
db.session.rollback()
return None
def get_monthly_usage(self, user_id: int, year: int = None, month: int = None) -> int:
"""Get total seconds transcribed by a user in a given month."""
if year is None:
year = date.today().year
if month is None:
month = date.today().month
result = db.session.query(func.sum(TranscriptionUsage.audio_duration_seconds)).filter(
TranscriptionUsage.user_id == user_id,
extract('year', TranscriptionUsage.date) == year,
extract('month', TranscriptionUsage.date) == month
).scalar()
return result or 0
def get_monthly_cost(self, user_id: int, year: int = None, month: int = None) -> float:
"""Get total estimated cost for a user in a given month."""
if year is None:
year = date.today().year
if month is None:
month = date.today().month
result = db.session.query(func.sum(TranscriptionUsage.estimated_cost)).filter(
TranscriptionUsage.user_id == user_id,
extract('year', TranscriptionUsage.date) == year,
extract('month', TranscriptionUsage.date) == month
).scalar()
return result or 0.0
def check_budget(self, user_id: int) -> Tuple[bool, float, Optional[str]]:
"""
Check if user is within transcription budget.
Returns:
(can_proceed, usage_percentage, message)
- can_proceed: False if hard cap (100%) reached
- usage_percentage: 0-100+
- message: Warning/error message if applicable
"""
try:
user = db.session.get(User, user_id)
if not user or not user.monthly_transcription_budget:
return (True, 0, None) # No budget = unlimited
current_usage = self.get_monthly_usage(user_id)
budget = user.monthly_transcription_budget
percentage = (current_usage / budget) * 100
# In the user's interface language: the exceeded message is
# shown to them as the error of the failed recording.
language = user.ui_language
if percentage >= 100:
return (False, percentage, translate(
'server.budget.transcriptionExceeded', language,
used=format_number(current_usage // 60, language),
budget=format_number(budget // 60, language)))
elif percentage >= 80:
return (True, percentage, translate(
'server.budget.transcriptionWarning', language,
percent=format_percent(percentage, language)))
else:
return (True, percentage, None)
except Exception as e:
logger.error(f"Failed to check transcription budget for user {user_id}: {e}")
# Fail open - allow the request if we can't check
return (True, 0, None)
def get_daily_stats(self, days: int = 30, user_id: int = None) -> List[Dict]:
"""Get daily transcription usage for charts."""
start_date = date.today() - timedelta(days=days - 1)
query = db.session.query(
TranscriptionUsage.date,
TranscriptionUsage.connector_type,
func.sum(TranscriptionUsage.audio_duration_seconds).label('seconds'),
func.sum(TranscriptionUsage.estimated_cost).label('cost')
).filter(TranscriptionUsage.date >= start_date)
if user_id:
query = query.filter(TranscriptionUsage.user_id == user_id)
results = query.group_by(TranscriptionUsage.date, TranscriptionUsage.connector_type).all()
# Organize by date
stats = {}
for r in results:
date_str = r.date.isoformat()
if date_str not in stats:
stats[date_str] = {'date': date_str, 'total_seconds': 0, 'total_minutes': 0, 'cost': 0.0, 'by_connector': {}}
stats[date_str]['total_seconds'] += r.seconds or 0
stats[date_str]['total_minutes'] = stats[date_str]['total_seconds'] // 60
stats[date_str]['cost'] += r.cost or 0
stats[date_str]['by_connector'][r.connector_type] = {
'seconds': r.seconds or 0,
'minutes': (r.seconds or 0) // 60
}
# Fill in missing dates with zeros
all_dates = []
current = start_date
while current <= date.today():
date_str = current.isoformat()
if date_str not in stats:
stats[date_str] = {'date': date_str, 'total_seconds': 0, 'total_minutes': 0, 'cost': 0.0, 'by_connector': {}}
all_dates.append(date_str)
current += timedelta(days=1)
return [stats[d] for d in sorted(all_dates)]
def get_monthly_stats(self, months: int = 12) -> List[Dict]:
"""Get monthly transcription usage for charts."""
results = db.session.query(
extract('year', TranscriptionUsage.date).label('year'),
extract('month', TranscriptionUsage.date).label('month'),
func.sum(TranscriptionUsage.audio_duration_seconds).label('seconds'),
func.sum(TranscriptionUsage.estimated_cost).label('cost')
).group_by('year', 'month').order_by('year', 'month').all()
by_month = {(int(r.year), int(r.month)): r for r in results}
# The last N calendar months up to this one, zeros included, so the
# last entry is always the current month (it used to be the last
# month WITH usage, which showed last month's total as "this month").
today = date.today()
out = []
y, m = today.year, today.month
for _ in range(max(months, 1)):
r = by_month.get((y, m))
seconds = (r.seconds or 0) if r else 0
out.append({'year': y, 'month': m, 'seconds': seconds, 'minutes': seconds // 60,
'cost': (r.cost or 0) if r else 0})
y, m = (y, m - 1) if m > 1 else (y - 1, 12)
return list(reversed(out))
def get_user_stats(self) -> List[Dict]:
"""Get per-user transcription usage breakdown for current month."""
today = date.today()
results = db.session.query(
User.id,
User.username,
User.monthly_transcription_budget,
func.sum(TranscriptionUsage.audio_duration_seconds).label('usage'),
func.sum(TranscriptionUsage.estimated_cost).label('cost')
).outerjoin(
TranscriptionUsage,
(User.id == TranscriptionUsage.user_id) &
(extract('year', TranscriptionUsage.date) == today.year) &
(extract('month', TranscriptionUsage.date) == today.month)
).group_by(User.id).all()
return [
{
'user_id': r.id,
'username': r.username,
'monthly_budget_seconds': r.monthly_transcription_budget,
'monthly_budget_minutes': (r.monthly_transcription_budget // 60) if r.monthly_transcription_budget else None,
'current_usage_seconds': r.usage or 0,
'current_usage_minutes': (r.usage or 0) // 60,
'cost': r.cost or 0,
'percentage': ((r.usage or 0) / r.monthly_transcription_budget * 100)
if r.monthly_transcription_budget else 0
}
for r in results
]
def get_today_usage(self, user_id: int = None) -> Dict:
"""Get today's transcription usage."""
today = date.today()
query = db.session.query(
func.sum(TranscriptionUsage.audio_duration_seconds).label('seconds'),
func.sum(TranscriptionUsage.estimated_cost).label('cost')
).filter(TranscriptionUsage.date == today)
if user_id:
query = query.filter(TranscriptionUsage.user_id == user_id)
result = query.first()
return {
'seconds': result.seconds or 0,
'minutes': (result.seconds or 0) // 60,
'cost': result.cost or 0
}
# Singleton instance
transcription_tracker = TranscriptionTracker()