Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
Add v1 endpoints for folder CRUD and transcription connector discovery
Murtaza Nasira207b744dfda
diff --git a/src/api/api_v1.py b/src/api/api_v1.pyindex bbe487f0..5c22da90 100644--- a/src/api/api_v1.py+++ b/src/api/api_v1.py@@ -131,6 +131,26 @@ OPENAPI_SPEC = {"default_transcription_model": {"type": "string"}}},+ "Folder": {+ "type": "object",+ "properties": {+ "id": {"type": "integer"},+ "name": {"type": "string"},+ "color": {"type": "string"},+ "group_id": {"type": "integer", "nullable": True},+ "is_group_folder": {"type": "boolean"},+ "custom_prompt": {"type": "string"},+ "default_language": {"type": "string"},+ "default_min_speakers": {"type": "integer"},+ "default_max_speakers": {"type": "integer"},+ "default_hotwords": {"type": "string"},+ "default_initial_prompt": {"type": "string"},+ "default_transcription_model": {"type": "string"},+ "protect_from_deletion": {"type": "boolean"},+ "retention_days": {"type": "integer", "nullable": True},+ "recording_count": {"type": "integer"}+ }+ },"Speaker": {"type": "object","properties": {@@ -314,6 +334,62 @@ OPENAPI_SPEC = {"put": {"tags": ["Tags"], "summary": "Update tag", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "color": {"type": "string"}, "custom_prompt": {"type": "string"}}}}}}, "responses": {"200": {"description": "Tag updated"}}},"delete": {"tags": ["Tags"], "summary": "Delete tag", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Tag deleted"}}}},+ "/folders": {+ "get": {"tags": ["Folders"], "summary": "List folders", "responses": {"200": {"description": "Array of folders the user can access", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/Folder"}}}}}}},+ "post": {"tags": ["Folders"], "summary": "Create folder", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}, "color": {"type": "string"}, "group_id": {"type": "integer", "nullable": True}, "custom_prompt": {"type": "string"}, "default_language": {"type": "string"}, "default_min_speakers": {"type": "integer"}, "default_max_speakers": {"type": "integer"}, "default_hotwords": {"type": "string"}, "default_initial_prompt": {"type": "string"}, "default_transcription_model": {"type": "string"}, "retention_days": {"type": "integer"}}}}}}, "responses": {"201": {"description": "Folder created"}}}+ },+ "/folders/{id}": {+ "get": {"tags": ["Folders"], "summary": "Get folder", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Folder", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Folder"}}}}}},+ "patch": {"tags": ["Folders"], "summary": "Update folder", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "color": {"type": "string"}, "custom_prompt": {"type": "string"}, "default_language": {"type": "string"}, "default_min_speakers": {"type": "integer"}, "default_max_speakers": {"type": "integer"}, "default_hotwords": {"type": "string"}, "default_initial_prompt": {"type": "string"}, "default_transcription_model": {"type": "string"}, "retention_days": {"type": "integer"}}}}}}, "responses": {"200": {"description": "Folder updated"}}},+ "delete": {"tags": ["Folders"], "summary": "Delete folder", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Folder deleted"}}}+ },+ "/transcription": {+ "get": {+ "tags": ["Transcription"],+ "summary": "Discover the active transcription connector and its accepted models",+ "description": "Returns the active connector name, a map of capability flags, the admin-curated model list, and the configured default model. Use this to drive client UIs and to know which values are valid for the `transcription_model` override on /recordings/{id}/transcribe and /recordings/upload.",+ "responses": {+ "200": {+ "description": "Connector info",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "connector": {"type": "string", "nullable": True, "description": "Active connector name (e.g. asr_endpoint, openai_transcribe, mistral, vibevoice)"},+ "capabilities": {+ "type": "object",+ "description": "Boolean flags indicating which optional fields the connector accepts",+ "properties": {+ "diarization": {"type": "boolean"},+ "speaker_count_control": {"type": "boolean"},+ "hotwords": {"type": "boolean"},+ "initial_prompt": {"type": "boolean"},+ "timestamps": {"type": "boolean"},+ "language_detection": {"type": "boolean"},+ "chunking": {"type": "boolean"}+ }+ },+ "models": {+ "type": "array",+ "description": "Models the admin has marked visible to users (or TRANSCRIPTION_MODELS_AVAILABLE entries when no DB list is set)",+ "items": {+ "type": "object",+ "properties": {+ "value": {"type": "string"},+ "label": {"type": "string"}+ }+ }+ },+ "default_model": {"type": "string", "nullable": True}+ }+ }+ }+ }+ }+ }+ }+ },"/speakers": {"get": {"tags": ["Speakers"], "summary": "List speakers", "responses": {"200": {"description": "List of speakers"}}},"post": {"tags": ["Speakers"], "summary": "Create speaker", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}}}}}}, "responses": {"201": {"description": "Speaker created"}}}@@ -340,6 +416,8 @@ OPENAPI_SPEC = {{"name": "Events", "description": "Calendar events"},{"name": "Audio", "description": "Audio file operations"},{"name": "Tags", "description": "Tag management"},+ {"name": "Folders", "description": "Folder management"},+ {"name": "Transcription", "description": "Transcription connector and model discovery"},{"name": "Speakers", "description": "Speaker management"},{"name": "Batch", "description": "Batch operations"},{"name": "Settings", "description": "User settings"}@@ -1421,6 +1499,195 @@ def remove_tag_from_recording(recording_id, tag_id):return jsonify({'success': True, 'message': 'Tag removed'})+# =============================================================================+# Folder Management+#+# These endpoints delegate to the existing web handlers in src/api/folders.py+# so permission semantics (group folders, member vs admin) match the web UI+# exactly. The web handlers already return jsonified, API-shaped responses+# (`folder.to_dict()` for success, `{"error": "..."}` for errors), so the+# delegation produces clean API output.+#+# Contract dependency: the v1 API's response shape on these routes is whatever+# the corresponding handler in folders.py returns. Changing those return+# shapes silently changes this API. A future cleanup should extract a+# services/folder.py layer that returns data dicts, with both the web and v1+# endpoints thin-wrapping with jsonify; that decouples the API contract from+# the web response framing.+# =============================================================================++@api_v1_bp.route('/folders', methods=['GET'])+@login_required+def list_folders():+ """List folders the user can access (personal + group folders)."""+ from src.api.folders import get_folders as _web_get_folders+ return _web_get_folders()+++@api_v1_bp.route('/folders', methods=['POST'])+@login_required+def create_folder():+ """Create a new folder. Accepts the same JSON body as the web endpoint."""+ from src.api.folders import create_folder as _web_create_folder+ return _web_create_folder()+++@api_v1_bp.route('/folders/<int:folder_id>', methods=['GET'])+@login_required+def get_folder(folder_id):+ """Get a single folder by id."""+ from src.models.organization import Folder, GroupMembership++ folder = db.session.get(Folder, folder_id)+ if not folder:+ return jsonify({'error': 'Folder not found'}), 404++ # Personal folders: must own it. Group folders: must be a member.+ if folder.group_id is None:+ if folder.user_id != current_user.id:+ return jsonify({'error': 'Permission denied'}), 403+ else:+ membership = GroupMembership.query.filter_by(+ user_id=current_user.id, group_id=folder.group_id+ ).first()+ if not membership:+ return jsonify({'error': 'Permission denied'}), 403++ folder_dict = folder.to_dict()+ if folder.group_id is None:+ folder_dict['can_edit'] = True+ else:+ membership = GroupMembership.query.filter_by(+ user_id=current_user.id, group_id=folder.group_id+ ).first()+ folder_dict['can_edit'] = bool(membership and membership.role == 'admin')+ return jsonify(folder_dict)+++@api_v1_bp.route('/folders/<int:folder_id>', methods=['PATCH', 'PUT'])+@login_required+def update_folder(folder_id):+ """Update a folder. Same JSON body as the web endpoint."""+ from src.api.folders import update_folder as _web_update_folder+ return _web_update_folder(folder_id)+++@api_v1_bp.route('/folders/<int:folder_id>', methods=['DELETE'])+@login_required+def delete_folder(folder_id):+ """Delete a folder. Recordings in it are unassigned."""+ from src.api.folders import delete_folder as _web_delete_folder+ return _web_delete_folder(folder_id)+++# =============================================================================+# Transcription Connector & Model Discovery+# =============================================================================++@api_v1_bp.route('/transcription', methods=['GET'])+@login_required+def get_transcription_info():+ """+ Return information about the active transcription connector so API+ clients can know which fields are accepted and which model values are+ valid for `transcription_model` overrides.++ Response shape:+ {+ "connector": "openai_transcribe",+ "capabilities": {+ "diarization": true,+ "speaker_count_control": false,+ "hotwords": true,+ "initial_prompt": true,+ "timestamps": true,+ "language_detection": true,+ "chunking": false+ },+ "models": [+ {"value": "gpt-4o-transcribe-diarize", "label": "GPT-4o Diarize"},+ ...+ ],+ "default_model": "gpt-4o-transcribe-diarize"+ }+ """+ from src.models import SystemSetting+ from src.config.app_config import (+ TRANSCRIPTION_MODEL,+ USE_NEW_TRANSCRIPTION_ARCHITECTURE,+ USE_ASR_ENDPOINT,+ )++ connector_name = None+ capabilities = {+ 'diarization': USE_ASR_ENDPOINT,+ 'speaker_count_control': USE_ASR_ENDPOINT,+ 'hotwords': USE_ASR_ENDPOINT,+ 'initial_prompt': USE_ASR_ENDPOINT,+ 'timestamps': True,+ 'language_detection': True,+ 'chunking': False,+ }+ if USE_NEW_TRANSCRIPTION_ARCHITECTURE:+ try:+ from src.services.transcription import get_registry+ registry = get_registry()+ connector_name = registry.get_active_connector_name()+ connector = registry.get_active_connector()+ if connector:+ capabilities = {+ 'diarization': connector.supports_diarization,+ 'speaker_count_control': connector.supports_speaker_count_control,+ 'hotwords': connector.supports_hotwords,+ 'initial_prompt': connector.supports_initial_prompt,+ 'timestamps': True,+ 'language_detection': True,+ 'chunking': connector.supports_chunking,+ }+ except Exception as e:+ current_app.logger.warning(f"Could not read connector capabilities: {e}")++ # Visible models: admin-curated DB list takes precedence over the+ # TRANSCRIPTION_MODELS_AVAILABLE env var.+ models = []+ raw = SystemSetting.get_setting('transcription_models_visible_json', None)+ if raw:+ try:+ parsed = json.loads(raw)+ if isinstance(parsed, list):+ for item in parsed:+ if isinstance(item, dict) and item.get('value'):+ models.append({+ 'value': item['value'],+ 'label': item.get('label') or item['value'],+ })+ elif isinstance(item, str) and item:+ models.append({'value': item, 'label': item})+ except Exception:+ models = []+ if not models:+ from src.config.app_config import (+ TRANSCRIPTION_MODELS_AVAILABLE,+ TRANSCRIPTION_MODEL_LABELS,+ )+ if TRANSCRIPTION_MODELS_AVAILABLE:+ labels = TRANSCRIPTION_MODEL_LABELS or []+ for i, value in enumerate(TRANSCRIPTION_MODELS_AVAILABLE):+ models.append({+ 'value': value,+ 'label': labels[i] if i < len(labels) else value,+ })++ default_model = SystemSetting.get_setting('transcription_default_model', None) or TRANSCRIPTION_MODEL or None++ return jsonify({+ 'connector': connector_name,+ 'capabilities': capabilities,+ 'models': models,+ 'default_model': default_model,+ })++# =============================================================================# Speaker Management# =============================================================================