Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

feat: configurable auto-export filename templates with rename migration for existing exports (#348)

Murtaza Nasird9803e1bc510
diff --git a/src/api/auth.py b/src/api/auth.py
index f14af1f9..21eaba00 100644
--- a/src/api/auth.py
+++ b/src/api/auth.py
@@ -657,6 +657,20 @@ def account():
current_user.chat_include_timestamps = 'chat_include_timestamps' in request.form
current_user.chat_timestamp_template_id = _ts_template_id('chat_timestamp_template_id')
+ # Check if this is the export filename template form (#348)
+ elif 'export_filename_template' in request.form:
+ template_value = (request.form.get('export_filename_template') or '').strip()
+ # Path separators would let a template escape the per-user export
+ # directory; reject them outright.
+ if '/' in template_value or '\\' in template_value:
+ error_msg = 'The filename template cannot contain path separators (/ or \\).'
+ if request.headers.get('X-Requested-With') == 'XMLHttpRequest' or request.accept_mimetypes.best == 'application/json':
+ return jsonify({'success': False, 'error': error_msg}), 400
+ flash(error_msg, 'danger')
+ return redirect(url_for('auth.account'))
+ # Empty string = use the default template (recording_{{id}})
+ current_user.export_filename_template = template_value if template_value else None
+
# Only update diarize if it's not locked by env var
if 'ASR_DIARIZE' not in os.environ:
current_user.diarize = 'diarize' in request.form
diff --git a/src/api/export_templates.py b/src/api/export_templates.py
index aa35374b..d75a2efe 100644
--- a/src/api/export_templates.py
+++ b/src/api/export_templates.py
@@ -160,3 +160,27 @@ def create_default_export_templates():
'success': True,
'templates': [default_template.to_dict()]
}), 201
+
+
+@export_templates_bp.route('/api/export/apply-filename-template', methods=['POST'])
+@login_required
+def apply_filename_template():
+ """Rename the current user's existing export files to match their current
+ filename template (#348).
+
+ Re-renders every exported recording's filename, renames the files on disk
+ (including "[deleted]_"-prefixed files, which keep their prefix) and
+ updates the stored export_filename values. Missing files are skipped.
+ """
+ from src.file_exporter import ENABLE_AUTO_EXPORT as auto_export_enabled
+ from src.file_exporter import apply_filename_template_for_user
+
+ if not auto_export_enabled:
+ return jsonify({'error': 'Auto-export is not enabled on this server'}), 400
+
+ try:
+ result = apply_filename_template_for_user(current_user.id)
+ return jsonify(result)
+ except Exception as e:
+ current_app.logger.error(f"Error applying export filename template: {e}")
+ return jsonify({'error': 'Failed to rename existing exports'}), 500
diff --git a/src/file_exporter.py b/src/file_exporter.py
index f6832aac..829ef594 100644
--- a/src/file_exporter.py
+++ b/src/file_exporter.py
@@ -130,17 +130,153 @@ def generate_safe_filename(recording):
return f"recording_{recording.id}"
+# Default filename template — reproduces the legacy "recording_{id}" naming
+# exactly, so users who never touch the setting see no behavior change (#348).
+DEFAULT_EXPORT_FILENAME_TEMPLATE = 'recording_{{id}}'
+
+# Maximum length of a rendered export filename (without the .md extension).
+MAX_EXPORT_FILENAME_LENGTH = 150
+
+# Characters illegal on common filesystems (plus path separators).
+_UNSAFE_FILENAME_CHARS = re.compile(r'[/\\:*?"<>|\x00-\x1f]')
+
+
+def sanitize_export_filename(name):
+ """
+ Make a rendered filename safe for common filesystems.
+
+ Strips path separators and characters illegal on Windows/macOS/Linux,
+ collapses whitespace runs to single spaces, trims dots/spaces at the ends
+ and caps the length. Unicode letters are preserved (deliberately NOT
+ secure_filename(), which would mangle non-ASCII titles). Returns '' if
+ nothing safe remains — callers must fall back to the legacy name.
+ """
+ if not name:
+ return ''
+ result = _UNSAFE_FILENAME_CHARS.sub('', name)
+ result = re.sub(r'\s+', ' ', result)
+ result = result.strip(' .')
+ if len(result) > MAX_EXPORT_FILENAME_LENGTH:
+ result = result[:MAX_EXPORT_FILENAME_LENGTH].strip(' .')
+ return result
+
+
+def render_export_filename(recording, user):
+ """
+ Render the export filename (WITHOUT the .md extension) for a recording
+ using the user's filename template.
+
+ Supported variables: {{id}}, {{title}}, {{filename}} (original filename
+ stem), and {{date}}/{{datetime}}/{{time}}/{{year}}/{{month}}/{{day}} from
+ recording.meeting_date (falling back to created_at). The result is
+ sanitized for filesystem safety; an empty result falls back to the legacy
+ "recording_{id}". If the rendered name collides (case-insensitively) with
+ a DIFFERENT recording's stored export filename for the same user, "_{id}"
+ is appended to keep names unique.
+ """
+ from src.models import Recording
+ from sqlalchemy import func
+
+ template = (getattr(user, 'export_filename_template', None) or '').strip()
+ if not template:
+ template = DEFAULT_EXPORT_FILENAME_TEMPLATE
+
+ dt = recording.meeting_date or recording.created_at
+ filename_stem = os.path.splitext(recording.original_filename)[0] if recording.original_filename else ''
+
+ variables = {
+ 'id': str(recording.id),
+ 'title': recording.title or '',
+ 'filename': filename_stem,
+ 'date': dt.strftime('%Y-%m-%d') if dt else '',
+ 'datetime': dt.strftime('%Y-%m-%d %H-%M') if dt else '',
+ 'time': dt.strftime('%H-%M') if dt else '',
+ 'year': dt.strftime('%Y') if dt else '',
+ 'month': dt.strftime('%m') if dt else '',
+ 'day': dt.strftime('%d') if dt else '',
+ }
+
+ result = template
+ for var_name, value in variables.items():
+ result = result.replace('{{' + var_name + '}}', value)
+
+ result = sanitize_export_filename(result)
+ if not result:
+ result = f"recording_{recording.id}"
+
+ # Uniqueness: a different recording of the same user already owns this
+ # name (case-insensitive) -> append the id to disambiguate.
+ try:
+ collision = Recording.query.filter(
+ Recording.user_id == recording.user_id,
+ Recording.id != recording.id,
+ func.lower(Recording.export_filename) == result.lower()
+ ).first()
+ except Exception:
+ collision = None
+ if collision is not None:
+ suffix = f"_{recording.id}"
+ if len(result) + len(suffix) > MAX_EXPORT_FILENAME_LENGTH:
+ result = result[:MAX_EXPORT_FILENAME_LENGTH - len(suffix)].strip(' .')
+ result = f"{result}{suffix}"
+
+ return result
+
+
+def get_stored_export_filename(recording):
+ """The authoritative on-disk name (no extension) for a recording's export.
+
+ Recordings exported before this feature have no stored name and keep
+ using the legacy "recording_{id}" so existing files remain addressable.
+ """
+ return recording.export_filename or f"recording_{recording.id}"
+
+
def get_export_filepath(user, recording):
"""Get the full export filepath for a recording."""
export_dir = get_export_directory(user)
- filename = generate_safe_filename(recording)
- return export_dir / f"{filename}.md"
+ return export_dir / f"{get_stored_export_filename(recording)}.md"
+
+
+# The delete endpoint removes the Recording row BEFORE calling
+# mark_export_as_deleted(), so with custom filenames the stored name can no
+# longer be read from the database at that point. This ORM listener captures
+# (user_id, export_filename) at delete time so the rename still finds the
+# right file. Best-effort, in-process only; the legacy "recording_{id}" scan
+# remains as fallback.
+_deleted_export_names = {}
+
+
+def _remember_deleted_export_name(mapper, connection, target):
+ try:
+ if len(_deleted_export_names) > 1000:
+ _deleted_export_names.clear()
+ _deleted_export_names[target.id] = (target.user_id, target.export_filename)
+ except Exception:
+ pass
+
+
+def _register_delete_listener():
+ try:
+ from sqlalchemy import event
+ from src.models import Recording
+ if not event.contains(Recording, 'after_delete', _remember_deleted_export_name):
+ event.listen(Recording, 'after_delete', _remember_deleted_export_name)
+ except Exception:
+ logger.debug("Could not register export-filename delete listener", exc_info=True)
+
+
+_register_delete_listener()
def mark_export_as_deleted(recording_id):
"""
Rename the export file to indicate the recording was deleted.
+ Uses the recording's stored export filename when available (from the DB
+ row if it still exists, or captured at ORM delete time otherwise) and
+ falls back to the legacy "recording_{id}" name.
+
Args:
recording_id: ID of the deleted recording
@@ -156,17 +292,47 @@ def mark_export_as_deleted(recording_id):
with app.app_context():
try:
- # We need to find the file - check all user directories
base_dir = Path(AUTO_EXPORT_DIR)
if not base_dir.exists():
return None
- # Look for the file in all user subdirectories
- for user_dir in base_dir.iterdir():
- if user_dir.is_dir():
- old_filepath = user_dir / f"recording_{recording_id}.md"
+ stored_name = None
+ user_dirs = None
+
+ def _dir_for(user_id):
+ user = db.session.get(User, user_id) if user_id else None
+ if user:
+ d = base_dir / secure_filename(user.username)
+ return [d] if d.is_dir() else []
+ return None
+
+ captured = _deleted_export_names.pop(recording_id, None)
+ if captured is not None:
+ user_id, stored_name = captured
+ user_dirs = _dir_for(user_id)
+ else:
+ recording = db.session.get(Recording, recording_id)
+ if recording:
+ stored_name = recording.export_filename
+ user_dirs = _dir_for(recording.user_id)
+
+ if user_dirs is None:
+ # Owner unknown — check all user directories.
+ user_dirs = [d for d in base_dir.iterdir() if d.is_dir()]
+
+ # Stored name first (authoritative), then the legacy id-based name.
+ candidates = []
+ if stored_name and '/' not in stored_name and '\\' not in stored_name:
+ candidates.append(stored_name)
+ legacy = f"recording_{recording_id}"
+ if legacy not in candidates:
+ candidates.append(legacy)
+
+ for user_dir in user_dirs:
+ for name in candidates:
+ old_filepath = user_dir / f"{name}.md"
if old_filepath.exists():
- new_filepath = user_dir / f"[deleted]_recording_{recording_id}.md"
+ new_filepath = user_dir / f"[deleted]_{name}.md"
old_filepath.rename(new_filepath)
logger.info(f"Marked export as deleted: {new_filepath}")
return str(new_filepath)
@@ -178,6 +344,79 @@ def mark_export_as_deleted(recording_id):
return None
+def apply_filename_template_for_user(user_id):
+ """
+ Re-render every exported recording's filename for a user under their
+ current template and rename the files on disk (the "[deleted]_"-prefixed
+ files of removed exports keep their prefix). Stored export_filename
+ values are updated to match. Missing files on disk are skipped.
+
+ Returns:
+ dict with counts: {'renamed': n, 'skipped': n, 'errors': n}
+ """
+ # Import here to avoid circular imports
+ from src.app import app, db
+ from src.models import Recording, User
+
+ with app.app_context():
+ renamed = 0
+ skipped = 0
+ errors = 0
+
+ user = db.session.get(User, user_id)
+ if not user:
+ return {'renamed': 0, 'skipped': 0, 'errors': 0}
+
+ user_dir = Path(AUTO_EXPORT_DIR) / secure_filename(user.username)
+
+ recordings = Recording.query.filter(Recording.user_id == user_id).all()
+ for recording in recordings:
+ try:
+ old_name = get_stored_export_filename(recording)
+ old_file = user_dir / f"{old_name}.md"
+ old_deleted = user_dir / f"[deleted]_{old_name}.md"
+
+ if not user_dir.is_dir() or not (old_file.exists() or old_deleted.exists()):
+ # Never exported (or file gone) — nothing to rename.
+ skipped += 1
+ continue
+
+ new_name = render_export_filename(recording, user)
+ if new_name == old_name:
+ # Persist the (unchanged) name so it becomes authoritative.
+ if recording.export_filename != new_name:
+ recording.export_filename = new_name
+ skipped += 1
+ continue
+
+ # Disk-level guard: if the target already exists (e.g. stale
+ # file, case-insensitive filesystem), disambiguate with the id.
+ if (user_dir / f"{new_name}.md").exists() or (user_dir / f"[deleted]_{new_name}.md").exists():
+ suffix = f"_{recording.id}"
+ if not new_name.endswith(suffix):
+ new_name = f"{new_name}{suffix}"
+
+ moved = False
+ if old_file.exists():
+ old_file.rename(user_dir / f"{new_name}.md")
+ moved = True
+ if old_deleted.exists():
+ old_deleted.rename(user_dir / f"[deleted]_{new_name}.md")
+ moved = True
+
+ recording.export_filename = new_name
+ if moved:
+ renamed += 1
+ else:
+ skipped += 1
+ except Exception as e:
+ logger.error(f"Failed to apply filename template to recording {recording.id}: {e}")
+ errors += 1
+
+ db.session.commit()
+ return {'renamed': renamed, 'skipped': skipped, 'errors': errors}
+
+
def format_duration(seconds):
"""Format duration in seconds to human-readable string."""
if not seconds:
@@ -510,9 +749,23 @@ def export_recording(recording_id):
# Get export directory for user
export_dir = get_export_directory(user)
- # Generate filename and path
- filename = generate_safe_filename(recording)
- filepath = export_dir / f"{filename}.md"
+ # Render and store the filename on first export (or when NULL from
+ # a legacy row that predates stored names). Once stored, the name
+ # is authoritative: re-exports overwrite that same file.
+ if not recording.export_filename:
+ new_name = render_export_filename(recording, user)
+ # A legacy export may already exist under "recording_{id}.md";
+ # migrate it to the new name so no orphan file is left behind.
+ legacy_file = export_dir / f"recording_{recording.id}.md"
+ if new_name != f"recording_{recording.id}" and legacy_file.exists():
+ try:
+ legacy_file.rename(export_dir / f"{new_name}.md")
+ except OSError:
+ pass
+ recording.export_filename = new_name
+ db.session.commit()
+
+ filepath = export_dir / f"{recording.export_filename}.md"
# Generate content
content = generate_markdown_content(
diff --git a/src/init_db.py b/src/init_db.py
index a4e4d941..4d9d27f6 100644
--- a/src/init_db.py
+++ b/src/init_db.py
@@ -426,6 +426,12 @@ def initialize_database(app):
if add_column_if_not_exists(engine, 'folder', 'export_template_id', 'INTEGER'):
app.logger.info("Added export_template_id column to folder table")
+ # Configurable auto-export filenames (#348)
+ if add_column_if_not_exists(engine, 'user', 'export_filename_template', 'VARCHAR(500)'):
+ app.logger.info("Added export_filename_template column to user table")
+ if add_column_if_not_exists(engine, 'recording', 'export_filename', 'VARCHAR(500)'):
+ app.logger.info("Added export_filename column to recording table")
+
# Add source tracking columns to internal_share table
if add_column_if_not_exists(engine, 'internal_share', 'source_type', "VARCHAR(20) DEFAULT 'manual'"):
app.logger.info("Added source_type column to internal_share table")
diff --git a/src/models/recording.py b/src/models/recording.py
index c3d7cf1b..a84a1b29 100644
--- a/src/models/recording.py
+++ b/src/models/recording.py
@@ -74,6 +74,12 @@ class Recording(db.Model):
resolved_hotwords = db.Column(db.Text, nullable=True)
resolved_initial_prompt = db.Column(db.Text, nullable=True)
+ # Rendered auto-export filename WITHOUT the .md extension (#348). Set on
+ # first export and authoritative from then on: re-exports overwrite this
+ # file and deletion renames it. Null = legacy "recording_{id}" naming, so
+ # existing deployments keep working with their existing files.
+ export_filename = db.Column(db.String(500), nullable=True)
+
# Folder relationship (one-to-many: a recording belongs to at most one folder)
folder_id = db.Column(db.Integer, db.ForeignKey('folder.id', ondelete='SET NULL'), nullable=True, index=True)
diff --git a/src/models/user.py b/src/models/user.py
index 364fef75..51ed6e64 100644
--- a/src/models/user.py
+++ b/src/models/user.py
@@ -63,6 +63,12 @@ class User(db.Model, UserMixin):
transcription_hotwords = db.Column(db.Text, nullable=True)
transcription_initial_prompt = db.Column(db.Text, nullable=True)
+ # Filename template for auto-exported markdown files (#348). Supports
+ # {{id}}, {{title}}, {{filename}}, {{date}}, {{datetime}}, {{time}},
+ # {{year}}, {{month}}, {{day}}. Null = default "recording_{{id}}"
+ # (exact legacy behavior).
+ export_filename_template = db.Column(db.String(500), nullable=True)
+
# Include timestamps in the transcript sent to the summarizer / chat (#304).
# Independent per feature; the *_template_id selects a transcript template to
# format the timestamps (null = a built-in default timestamp format).
diff --git a/static/locales/de.json b/static/locales/de.json
index 60bb7ddf..12716c82 100644
--- a/static/locales/de.json
+++ b/static/locales/de.json
@@ -753,7 +753,17 @@
"bulkExportButton": "Alle auf Datenträger exportieren",
"bulkExportRunning": "Exportiere…",
"bulkExportResult": "{{exported}} von {{total}} Aufnahmen exportiert.",
- "bulkExportFailed": "Export der Aufnahmen fehlgeschlagen."
+ "bulkExportFailed": "Export der Aufnahmen fehlgeschlagen.",
+ "filenameTemplateTitle": "Dateinamensvorlage für Exporte",
+ "filenameTemplateDescription": "Passen Sie die Dateinamen der automatisch exportierten Markdown-Dateien an. Leer lassen für den Standard (recording_{{id}}).",
+ "filenameTemplateHelp": "Verfügbare Variablen:",
+ "filenameTemplateSaved": "Dateinamensvorlage gespeichert.",
+ "filenameTemplateInvalid": "Die Dateinamensvorlage darf keine Pfadtrennzeichen (/ oder \\) enthalten.",
+ "filenameSavedRenameNote": "Gespeichert. Bereits exportierte Dateien behalten ihre Namen, bis Sie \"Vorhandene Exporte umbenennen\" verwenden.",
+ "renameExisting": "Vorhandene Exporte umbenennen",
+ "renameConfirm": "Alle bereits exportierten Dateien an die aktuelle Vorlage anpassen?",
+ "renameResult": "{{renamed}} Dateien umbenannt, {{skipped}} übersprungen, Fehler: {{errors}}.",
+ "renameFailed": "Umbenennen der vorhandenen Exporte fehlgeschlagen."
},
"fileSize": {
"bytes": "{{count}} B",
diff --git a/static/locales/en.json b/static/locales/en.json
index 0b1ee5fe..c75ccd59 100644
--- a/static/locales/en.json
+++ b/static/locales/en.json
@@ -753,7 +753,17 @@
"bulkExportButton": "Export all to disk",
"bulkExportRunning": "Exporting…",
"bulkExportResult": "Exported {{exported}} of {{total}} recordings.",
- "bulkExportFailed": "Failed to export recordings."
+ "bulkExportFailed": "Failed to export recordings.",
+ "filenameTemplateTitle": "Export filename template",
+ "filenameTemplateDescription": "Customize the filenames of auto-exported markdown files. Leave empty to use the default (recording_{{id}}).",
+ "filenameTemplateHelp": "Available variables:",
+ "filenameTemplateSaved": "Export filename template saved.",
+ "filenameTemplateInvalid": "The filename template cannot contain path separators (/ or \\).",
+ "filenameSavedRenameNote": "Saved. Previously exported files keep their names until you use \"Rename existing exports\".",
+ "renameExisting": "Rename existing exports",
+ "renameConfirm": "Rename all previously exported files to match the current template?",
+ "renameResult": "Renamed {{renamed}} files, skipped {{skipped}}, errors: {{errors}}.",
+ "renameFailed": "Failed to rename existing exports."
},
"fileSize": {
"bytes": "{{count}} B",
diff --git a/static/locales/es.json b/static/locales/es.json
index 34c4fe83..4f2b5aae 100644
--- a/static/locales/es.json
+++ b/static/locales/es.json
@@ -753,7 +753,17 @@
"bulkExportButton": "Exportar todo al disco",
"bulkExportRunning": "Exportando…",
"bulkExportResult": "{{exported}} de {{total}} grabaciones exportadas.",
- "bulkExportFailed": "No se pudieron exportar las grabaciones."
+ "bulkExportFailed": "No se pudieron exportar las grabaciones.",
+ "filenameTemplateTitle": "Plantilla de nombre de archivo de exportación",
+ "filenameTemplateDescription": "Personaliza los nombres de los archivos markdown exportados automáticamente. Déjalo vacío para usar el valor predeterminado (recording_{{id}}).",
+ "filenameTemplateHelp": "Variables disponibles:",
+ "filenameTemplateSaved": "Plantilla de nombre de archivo guardada.",
+ "filenameTemplateInvalid": "La plantilla de nombre de archivo no puede contener separadores de ruta (/ o \\).",
+ "filenameSavedRenameNote": "Guardado. Los archivos ya exportados conservan sus nombres hasta que uses \"Renombrar exportaciones existentes\".",
+ "renameExisting": "Renombrar exportaciones existentes",
+ "renameConfirm": "¿Renombrar todos los archivos ya exportados para que coincidan con la plantilla actual?",
+ "renameResult": "{{renamed}} archivos renombrados, {{skipped}} omitidos, errores: {{errors}}.",
+ "renameFailed": "No se pudieron renombrar las exportaciones existentes."
},
"fileSize": {
"bytes": "{{count}} B",
diff --git a/static/locales/fr.json b/static/locales/fr.json
index f55435dc..ebd49aa8 100644
--- a/static/locales/fr.json
+++ b/static/locales/fr.json
@@ -753,7 +753,17 @@
"bulkExportButton": "Tout exporter sur le disque",
"bulkExportRunning": "Exportation…",
"bulkExportResult": "{{exported}} enregistrement(s) sur {{total}} exporté(s).",
- "bulkExportFailed": "Échec de l'exportation des enregistrements."
+ "bulkExportFailed": "Échec de l'exportation des enregistrements.",
+ "filenameTemplateTitle": "Modèle de nom de fichier d'exportation",
+ "filenameTemplateDescription": "Personnalisez les noms des fichiers markdown exportés automatiquement. Laissez vide pour utiliser la valeur par défaut (recording_{{id}}).",
+ "filenameTemplateHelp": "Variables disponibles :",
+ "filenameTemplateSaved": "Modèle de nom de fichier enregistré.",
+ "filenameTemplateInvalid": "Le modèle de nom de fichier ne peut pas contenir de séparateurs de chemin (/ ou \\).",
+ "filenameSavedRenameNote": "Enregistré. Les fichiers déjà exportés conservent leurs noms jusqu'à ce que vous utilisiez « Renommer les exportations existantes ».",
+ "renameExisting": "Renommer les exportations existantes",
+ "renameConfirm": "Renommer tous les fichiers déjà exportés pour correspondre au modèle actuel ?",
+ "renameResult": "{{renamed}} fichier(s) renommé(s), {{skipped}} ignoré(s), erreurs : {{errors}}.",
+ "renameFailed": "Échec du renommage des exportations existantes."
},
"fileSize": {
"bytes": "{{count}} B",
diff --git a/static/locales/pt-BR.json b/static/locales/pt-BR.json
index 2581dde7..c687c290 100644
--- a/static/locales/pt-BR.json
+++ b/static/locales/pt-BR.json
@@ -753,7 +753,17 @@
"bulkExportButton": "Exportar tudo para o disco",
"bulkExportRunning": "Exportando…",
"bulkExportResult": "{{exported}} de {{total}} gravações exportadas.",
- "bulkExportFailed": "Falha ao exportar as gravações."
+ "bulkExportFailed": "Falha ao exportar as gravações.",
+ "filenameTemplateTitle": "Modelo de nome de arquivo de exportação",
+ "filenameTemplateDescription": "Personalize os nomes dos arquivos markdown exportados automaticamente. Deixe vazio para usar o padrão (recording_{{id}}).",
+ "filenameTemplateHelp": "Variáveis disponíveis:",
+ "filenameTemplateSaved": "Modelo de nome de arquivo salvo.",
+ "filenameTemplateInvalid": "O modelo de nome de arquivo não pode conter separadores de caminho (/ ou \\).",
+ "filenameSavedRenameNote": "Salvo. Os arquivos já exportados mantêm seus nomes até você usar \"Renomear exportações existentes\".",
+ "renameExisting": "Renomear exportações existentes",
+ "renameConfirm": "Renomear todos os arquivos já exportados para corresponder ao modelo atual?",
+ "renameResult": "{{renamed}} arquivos renomeados, {{skipped}} ignorados, erros: {{errors}}.",
+ "renameFailed": "Falha ao renomear as exportações existentes."
},
"fileSize": {
"bytes": "{{count}} B",
diff --git a/static/locales/ru.json b/static/locales/ru.json
index ce5ae62a..bebe7094 100644
--- a/static/locales/ru.json
+++ b/static/locales/ru.json
@@ -753,7 +753,17 @@
"bulkExportButton": "Экспортировать всё на диск",
"bulkExportRunning": "Экспорт…",
"bulkExportResult": "Экспортировано {{exported}} из {{total}} записей.",
- "bulkExportFailed": "Не удалось экспортировать записи."
+ "bulkExportFailed": "Не удалось экспортировать записи.",
+ "filenameTemplateTitle": "Шаблон имени файла экспорта",
+ "filenameTemplateDescription": "Настройте имена автоматически экспортируемых файлов markdown. Оставьте пустым для значения по умолчанию (recording_{{id}}).",
+ "filenameTemplateHelp": "Доступные переменные:",
+ "filenameTemplateSaved": "Шаблон имени файла сохранён.",
+ "filenameTemplateInvalid": "Шаблон имени файла не может содержать разделители пути (/ или \\).",
+ "filenameSavedRenameNote": "Сохранено. Ранее экспортированные файлы сохраняют свои имена, пока вы не воспользуетесь «Переименовать существующие экспорты».",
+ "renameExisting": "Переименовать существующие экспорты",
+ "renameConfirm": "Переименовать все ранее экспортированные файлы в соответствии с текущим шаблоном?",
+ "renameResult": "Переименовано файлов: {{renamed}}, пропущено: {{skipped}}, ошибок: {{errors}}.",
+ "renameFailed": "Не удалось переименовать существующие экспорты."
},
"fileSize": {
"bytes": "{{count}} Б",
diff --git a/static/locales/zh.json b/static/locales/zh.json
index 64f38a6f..22d15964 100644
--- a/static/locales/zh.json
+++ b/static/locales/zh.json
@@ -753,7 +753,17 @@
"bulkExportButton": "全部导出到磁盘",
"bulkExportRunning": "正在导出…",
"bulkExportResult": "已导出 {{total}} 条录音中的 {{exported}} 条。",
- "bulkExportFailed": "导出录音失败。"
+ "bulkExportFailed": "导出录音失败。",
+ "filenameTemplateTitle": "导出文件名模板",
+ "filenameTemplateDescription": "自定义自动导出的 markdown 文件的文件名。留空则使用默认值(recording_{{id}})。",
+ "filenameTemplateHelp": "可用变量:",
+ "filenameTemplateSaved": "导出文件名模板已保存。",
+ "filenameTemplateInvalid": "文件名模板不能包含路径分隔符(/ 或 \\)。",
+ "filenameSavedRenameNote": "已保存。之前导出的文件将保留其名称,直到您使用\"重命名现有导出文件\"。",
+ "renameExisting": "重命名现有导出文件",
+ "renameConfirm": "将所有之前导出的文件重命名以匹配当前模板?",
+ "renameResult": "已重命名 {{renamed}} 个文件,跳过 {{skipped}} 个,错误 {{errors}} 个。",
+ "renameFailed": "重命名现有导出文件失败。"
},
"fileSize": {
"bytes": "{{count}} B",
diff --git a/templates/account.html b/templates/account.html
index 4f5f3690..002826af 100644
--- a/templates/account.html
+++ b/templates/account.html
@@ -1433,6 +1433,31 @@
</button>
</div>
</div>
+
+ <!-- Export filename template (#348) -->
+ <div class="bg-[var(--bg-secondary)] rounded-lg border border-[var(--border-primary)] p-6">
+ <h3 class="text-lg font-semibold text-[var(--text-primary)]" data-i18n="exportTemplates.filenameTemplateTitle">Export filename template</h3>
+ <p class="text-sm text-[var(--text-secondary)] mt-1" data-i18n="exportTemplates.filenameTemplateDescription">Customize the filenames of auto-exported markdown files. Leave empty to use the default (recording_{% raw %}{{id}}{% endraw %}).</p>
+ <form id="exportFilenameForm" method="POST" action="{{ url_for('auth.account') }}" class="mt-4 space-y-3">
+ <input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>
+ <input type="text" id="exportFilenameTemplateInput" name="export_filename_template" value="{{ current_user.export_filename_template or '' }}" maxlength="500" class="w-full px-3 py-2 bg-[var(--bg-primary)] text-[var(--text-primary)] border border-[var(--border-primary)] rounded-md focus:outline-none focus:ring-2 focus:ring-[var(--ring-focus)] font-mono text-sm" placeholder="{% raw %}{{date}} {{title}}{% endraw %}">
+ <p class="text-xs text-[var(--text-light)]">
+ <span data-i18n="exportTemplates.filenameTemplateHelp">Available variables:</span>
+ {% raw %}<code>{{id}}</code>, <code>{{title}}</code>, <code>{{filename}}</code>, <code>{{date}}</code>, <code>{{datetime}}</code>, <code>{{time}}</code>, <code>{{year}}</code>, <code>{{month}}</code>, <code>{{day}}</code>{% endraw %}
+ </p>
+ <p id="exportFilenameStatus" class="text-sm hidden"></p>
+ <div class="flex flex-wrap gap-3">
+ <button type="submit" class="btn btn--primary">
+ <i class="fas fa-save mr-2"></i>
+ <span data-i18n="exportTemplates.save">Save</span>
+ </button>
+ <button type="button" id="renameExportsBtn" class="px-4 py-2 bg-[var(--bg-tertiary)] text-[var(--text-secondary)] rounded-md hover:bg-[var(--bg-accent-light)] transition-colors disabled:opacity-60 disabled:cursor-not-allowed">
+ <i class="fas fa-pen mr-2"></i>
+ <span data-i18n="exportTemplates.renameExisting">Rename existing exports</span>
+ </button>
+ </div>
+ </form>
+ </div>
{% endif %}
<!-- Export Templates Grid -->
@@ -7773,6 +7798,93 @@ curl "https://your-speakr-instance.com/api/recordings?token=YOUR_TOKEN_HERE"</co
}
});
+ // Export filename template (#348): saves via the /account settings
+ // form branch (field presence selects the branch server-side). When
+ // the template changed, surface a note that previously exported
+ // files keep their names until "Rename existing exports" is used.
+ (function () {
+ const form = document.getElementById('exportFilenameForm');
+ if (!form) return;
+ const input = document.getElementById('exportFilenameTemplateInput');
+ const statusEl = document.getElementById('exportFilenameStatus');
+ let savedValue = input.value.trim();
+
+ const showFilenameStatus = (msg, isError) => {
+ if (!statusEl) return;
+ statusEl.textContent = msg;
+ statusEl.classList.remove('hidden');
+ statusEl.style.color = isError ? 'var(--color-danger, #ef4444)' : 'var(--text-secondary)';
+ };
+
+ form.addEventListener('submit', async (e) => {
+ e.preventDefault();
+ const submitBtn = form.querySelector('[type=submit]');
+ if (submitBtn) submitBtn.disabled = true;
+ try {
+ const fd = new FormData(form);
+ const csrfToken = form.querySelector('[name=csrf_token]')?.value;
+ const response = await fetch(form.action || window.location.href, {
+ method: 'POST',
+ headers: {
+ 'X-Requested-With': 'XMLHttpRequest',
+ ...(csrfToken ? { 'X-CSRFToken': csrfToken } : {})
+ },
+ body: fd,
+ credentials: 'same-origin'
+ });
+ const result = await response.json().catch(() => ({}));
+ if (!response.ok) {
+ throw new Error(result.error || t('exportTemplates.filenameTemplateInvalid'));
+ }
+ const changed = input.value.trim() !== savedValue;
+ savedValue = input.value.trim();
+ if (changed) {
+ showFilenameStatus(t('exportTemplates.filenameSavedRenameNote'), false);
+ } else if (statusEl) {
+ statusEl.classList.add('hidden');
+ }
+ showToast(t('exportTemplates.filenameTemplateSaved'), 'success');
+ } catch (err) {
+ console.error('[export filename template]', err);
+ const msg = (err && err.message) || t('exportTemplates.filenameTemplateInvalid');
+ showFilenameStatus(msg, true);
+ showToast(msg, 'error');
+ } finally {
+ if (submitBtn) submitBtn.disabled = false;
+ }
+ });
+
+ document.getElementById('renameExportsBtn')?.addEventListener('click', async (e) => {
+ if (!confirm(t('exportTemplates.renameConfirm'))) return;
+ const btn = e.currentTarget;
+ btn.disabled = true;
+ try {
+ const csrfToken = document.querySelector('meta[name="csrf-token"]')?.getAttribute('content');
+ const response = await fetch('/api/export/apply-filename-template', {
+ method: 'POST',
+ headers: { 'X-CSRFToken': csrfToken }
+ });
+ const result = await response.json();
+ if (!response.ok) {
+ throw new Error(result.error || t('exportTemplates.renameFailed'));
+ }
+ const msg = t('exportTemplates.renameResult', {
+ renamed: result.renamed,
+ skipped: result.skipped,
+ errors: result.errors
+ });
+ showFilenameStatus(msg, false);
+ showToast(msg, 'success');
+ } catch (error) {
+ console.error('Rename exports error:', error);
+ showFilenameStatus((error && error.message) || t('exportTemplates.renameFailed'), true);
+ showToast(t('exportTemplates.renameFailed'), 'error');
+ } finally {
+ btn.disabled = false;
+ }
+ });
+ })();
+
// ============================================
// Naming Templates Management
// ============================================
diff --git a/tests/test_export_filename_template.py b/tests/test_export_filename_template.py
new file mode 100644
index 00000000..26063c6d
--- /dev/null
+++ b/tests/test_export_filename_template.py
@@ -0,0 +1,406 @@
+"""Tests for configurable auto-export filename templates (#348).
+
+Covers:
+ - Default template (NULL) yields the legacy "recording_{id}" name
+ - Custom templates render {{id}}/{{title}}/{{filename}}/date variables
+ - Filesystem-unsafe characters are stripped, whitespace collapsed
+ - Case-insensitive collisions with another recording's stored name append _{id}
+ - Re-export writes to the stored (authoritative) filename
+ - mark_export_as_deleted renames the stored name (incl. after row deletion)
+ - POST /api/export/apply-filename-template renames on disk + updates DB
+ - Unauthenticated requests to the rename endpoint are rejected
+ - POST /account validation for the template setting
+
+File exports go to a per-test temporary directory (AUTO_EXPORT_DIR patched).
+
+SHARED-DB: every assertion is scoped to the user/recordings the test created.
+"""
+
+import os
+import shutil
+import sys
+import tempfile
+import uuid
+from contextlib import contextmanager
+from datetime import datetime
+from unittest.mock import patch
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.app import app, db
+from src.models import User, Recording
+from src import file_exporter
+from src.file_exporter import (
+ render_export_filename,
+ sanitize_export_filename,
+ export_recording,
+ mark_export_as_deleted,
+ apply_filename_template_for_user,
+)
+
+app.config["WTF_CSRF_ENABLED"] = False
+
+
+# --------------------------------------------------------------------------- #
+# Helpers
+# --------------------------------------------------------------------------- #
+
+def _mk_user(prefix="xf", template=None):
+ suffix = uuid.uuid4().hex[:8]
+ user = User(
+ username=f"{prefix}_{suffix}",
+ email=f"{prefix}_{suffix}@local.test",
+ password="x",
+ export_filename_template=template,
+ )
+ db.session.add(user)
+ db.session.commit()
+ return user
+
+
+def _login(client, user):
+ with client.session_transaction() as sess:
+ sess["_user_id"] = str(user.id)
+ sess["_fresh"] = True
+
+
+def _mk_recording(user, **kwargs):
+ rec = Recording(
+ user_id=user.id,
+ title=kwargs.pop("title", f"rec_{uuid.uuid4().hex[:8]}"),
+ status=kwargs.pop("status", "COMPLETED"),
+ audio_path=kwargs.pop("audio_path", "local://recordings/x.mp3"),
+ original_filename=kwargs.pop("original_filename", "x.mp3"),
+ transcription=kwargs.pop("transcription", "some transcript text"),
+ **kwargs,
+ )
+ db.session.add(rec)
+ db.session.commit()
+ return rec
+
+
+@contextmanager
+def _export_env():
+ """Enable auto-export against a throwaway directory."""
+ tmpdir = tempfile.mkdtemp(prefix="speakr_export_test_")
+ try:
+ with patch.object(file_exporter, "ENABLE_AUTO_EXPORT", True), \
+ patch.object(file_exporter, "AUTO_EXPORT_DIR", tmpdir), \
+ patch.object(file_exporter, "AUTO_EXPORT_TRANSCRIPTION", True), \
+ patch.object(file_exporter, "AUTO_EXPORT_SUMMARY", True):
+ yield tmpdir
+ finally:
+ shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+def _user_dir(tmpdir, user):
+ from werkzeug.utils import secure_filename
+ return os.path.join(tmpdir, secure_filename(user.username))
+
+
+# --------------------------------------------------------------------------- #
+# Rendering
+# --------------------------------------------------------------------------- #
+
+def test_default_template_yields_legacy_name():
+ with app.app_context():
+ user = _mk_user(template=None)
+ rec = _mk_recording(user, title="Anything At All")
+ assert render_export_filename(rec, user) == f"recording_{rec.id}"
+
+
+def test_custom_template_renders_variables():
+ with app.app_context():
+ user = _mk_user(template="{{date}} {{title}} ({{filename}}) [{{id}}]")
+ rec = _mk_recording(
+ user,
+ title="Weekly Sync",
+ original_filename="audio file.m4a",
+ meeting_date=datetime(2025, 3, 14, 9, 30),
+ )
+ assert render_export_filename(rec, user) == (
+ f"2025-03-14 Weekly Sync (audio file) [{rec.id}]"
+ )
+
+
+def test_date_variables_fall_back_to_created_at():
+ with app.app_context():
+ user = _mk_user(template="{{year}}-{{month}}-{{day}} {{time}}")
+ rec = _mk_recording(user, meeting_date=None,
+ created_at=datetime(2024, 12, 31, 23, 5))
+ assert render_export_filename(rec, user) == "2024-12-31 23-05"
+
+
+def test_unsafe_characters_are_stripped():
+ with app.app_context():
+ user = _mk_user(template="{{title}}")
+ rec = _mk_recording(user, title='A/B\\C:D*E?F"G<H>I|J')
+ assert render_export_filename(rec, user) == "ABCDEFGHIJ"
+
+
+def test_whitespace_collapsed_and_edges_trimmed():
+ assert sanitize_export_filename(" Hello World.. ") == "Hello World"
+ assert sanitize_export_filename("...") == ""
+ # Unicode letters must survive (no secure_filename mangling)
+ assert sanitize_export_filename("Réunion générale — Überblick") == "Réunion générale — Überblick"
+
+
+def test_empty_render_falls_back_to_legacy_name():
+ with app.app_context():
+ user = _mk_user(template="{{title}}")
+ rec = _mk_recording(user, title="???") # sanitizes to empty
+ assert render_export_filename(rec, user) == f"recording_{rec.id}"
+
+
+def test_length_capped():
+ with app.app_context():
+ user = _mk_user(template="{{title}}")
+ rec = _mk_recording(user, title="x" * 400)
+ assert len(render_export_filename(rec, user)) <= 150
+
+
+def test_collision_appends_id():
+ with app.app_context():
+ user = _mk_user(template="{{title}}")
+ rec1 = _mk_recording(user, title="Meeting")
+ rec2 = _mk_recording(user, title="meeting") # case-insensitive clash
+ rec1.export_filename = render_export_filename(rec1, user)
+ db.session.commit()
+ assert rec1.export_filename == "Meeting"
+ assert render_export_filename(rec2, user) == f"meeting_{rec2.id}"
+
+
+def test_no_collision_across_users():
+ with app.app_context():
+ user_a = _mk_user(template="{{title}}")
+ user_b = _mk_user(template="{{title}}")
+ rec_a = _mk_recording(user_a, title="Standup")
+ rec_a.export_filename = "Standup"
+ db.session.commit()
+ rec_b = _mk_recording(user_b, title="Standup")
+ assert render_export_filename(rec_b, user_b) == "Standup"
+
+
+# --------------------------------------------------------------------------- #
+# Export flow
+# --------------------------------------------------------------------------- #
+
+def test_export_stores_filename_and_reexport_uses_it():
+ with app.app_context(), _export_env() as tmpdir:
+ user = _mk_user(template="{{title}}")
+ rec = _mk_recording(user, title="Project Kickoff")
+
+ path1 = export_recording(rec.id)
+ assert path1 is not None
+ assert os.path.basename(path1) == "Project Kickoff.md"
+ assert os.path.exists(path1)
+
+ db.session.expire_all()
+ rec = db.session.get(Recording, rec.id)
+ assert rec.export_filename == "Project Kickoff"
+
+ # Changing the template does NOT move already-exported files:
+ # the stored name stays authoritative on re-export.
+ user = db.session.get(User, user.id)
+ user.export_filename_template = "{{id}}_{{title}}"
+ db.session.commit()
+
+ path2 = export_recording(rec.id)
+ assert path2 == path1
+ exported = os.listdir(_user_dir(tmpdir, user))
+ assert exported == ["Project Kickoff.md"]
+
+
+def test_export_default_template_writes_legacy_path():
+ with app.app_context(), _export_env() as tmpdir:
+ user = _mk_user(template=None)
+ rec = _mk_recording(user)
+ path = export_recording(rec.id)
+ assert os.path.basename(path) == f"recording_{rec.id}.md"
+ db.session.expire_all()
+ assert db.session.get(Recording, rec.id).export_filename == f"recording_{rec.id}"
+
+
+# --------------------------------------------------------------------------- #
+# Deletion marking
+# --------------------------------------------------------------------------- #
+
+def test_mark_export_as_deleted_uses_stored_name():
+ with app.app_context(), _export_env() as tmpdir:
+ user = _mk_user(template="{{title}}")
+ rec = _mk_recording(user, title="Board Meeting")
+ rec.export_filename = "Board Meeting"
+ db.session.commit()
+
+ udir = _user_dir(tmpdir, user)
+ os.makedirs(udir, exist_ok=True)
+ with open(os.path.join(udir, "Board Meeting.md"), "w") as f:
+ f.write("content")
+
+ rec_id = rec.id
+ # Production order: row is deleted BEFORE mark_export_as_deleted runs.
+ db.session.delete(rec)
+ db.session.commit()
+
+ new_path = mark_export_as_deleted(rec_id)
+ assert new_path is not None
+ assert os.path.basename(new_path) == "[deleted]_Board Meeting.md"
+ assert os.path.exists(new_path)
+ assert not os.path.exists(os.path.join(udir, "Board Meeting.md"))
+
+
+def test_mark_export_as_deleted_legacy_fallback():
+ with app.app_context(), _export_env() as tmpdir:
+ user = _mk_user()
+ rec = _mk_recording(user) # no export_filename stored
+ rec_id = rec.id
+
+ udir = _user_dir(tmpdir, user)
+ os.makedirs(udir, exist_ok=True)
+ with open(os.path.join(udir, f"recording_{rec_id}.md"), "w") as f:
+ f.write("content")
+
+ db.session.delete(rec)
+ db.session.commit()
+
+ new_path = mark_export_as_deleted(rec_id)
+ assert new_path is not None
+ assert os.path.basename(new_path) == f"[deleted]_recording_{rec_id}.md"
+
+
+# --------------------------------------------------------------------------- #
+# Rename migration endpoint
+# --------------------------------------------------------------------------- #
+
+def test_apply_filename_template_endpoint_renames_disk_and_db():
+ with app.app_context(), _export_env() as tmpdir:
+ user = _mk_user(template=None)
+ rec1 = _mk_recording(user, title="Alpha Review")
+ rec2 = _mk_recording(user, title="Beta Review")
+ rec3 = _mk_recording(user, title="Never Exported")
+
+ # Simulate legacy exports on disk (NULL export_filename in DB).
+ udir = _user_dir(tmpdir, user)
+ os.makedirs(udir, exist_ok=True)
+ for rec in (rec1, rec2):
+ with open(os.path.join(udir, f"recording_{rec.id}.md"), "w") as f:
+ f.write("content")
+ # A deleted-marked export keeps its prefix through the rename.
+ rec4 = _mk_recording(user, title="Old One")
+ rec4.export_filename = f"recording_{rec4.id}"
+ db.session.commit()
+ with open(os.path.join(udir, f"[deleted]_recording_{rec4.id}.md"), "w") as f:
+ f.write("content")
+
+ user.export_filename_template = "{{title}}"
+ db.session.commit()
+
+ client = app.test_client()
+ _login(client, user)
+ resp = client.post("/api/export/apply-filename-template")
+ assert resp.status_code == 200
+ result = resp.get_json()
+ assert result["renamed"] == 3
+ assert result["errors"] == 0
+ assert result["skipped"] >= 1 # rec3 had no file on disk
+
+ files = sorted(os.listdir(udir))
+ assert "Alpha Review.md" in files
+ assert "Beta Review.md" in files
+ assert "[deleted]_Old One.md" in files
+ assert f"recording_{rec1.id}.md" not in files
+
+ db.session.expire_all()
+ assert db.session.get(Recording, rec1.id).export_filename == "Alpha Review"
+ assert db.session.get(Recording, rec2.id).export_filename == "Beta Review"
+ assert db.session.get(Recording, rec4.id).export_filename == "Old One"
+
+
+def test_apply_filename_template_skips_missing_files():
+ with app.app_context(), _export_env():
+ user = _mk_user(template="{{title}}")
+ rec = _mk_recording(user, title="Ghost")
+ rec.export_filename = "Some Old Name" # file never written / missing
+ db.session.commit()
+
+ result = apply_filename_template_for_user(user.id)
+ assert result["errors"] == 0
+ assert result["renamed"] == 0
+ assert result["skipped"] >= 1
+ db.session.expire_all()
+ # Stored name untouched because there was nothing to rename.
+ assert db.session.get(Recording, rec.id).export_filename == "Some Old Name"
+
+
+def test_apply_filename_template_endpoint_disabled_returns_400():
+ with app.app_context():
+ user = _mk_user()
+ client = app.test_client()
+ _login(client, user)
+ with patch.object(file_exporter, "ENABLE_AUTO_EXPORT", False):
+ resp = client.post("/api/export/apply-filename-template")
+ assert resp.status_code == 400
+
+
+def test_apply_filename_template_requires_login():
+ client = app.test_client()
+ with patch.object(file_exporter, "ENABLE_AUTO_EXPORT", True):
+ resp = client.post("/api/export/apply-filename-template")
+ assert resp.status_code in (302, 401)
+
+
+# --------------------------------------------------------------------------- #
+# Settings form (POST /account)
+# --------------------------------------------------------------------------- #
+
+def test_account_post_saves_template():
+ with app.app_context():
+ user = _mk_user()
+ client = app.test_client()
+ _login(client, user)
+ resp = client.post(
+ "/account",
+ data={"export_filename_template": "{{date}} {{title}}"},
+ headers={"X-Requested-With": "XMLHttpRequest"},
+ )
+ assert resp.status_code == 200
+ db.session.expire_all()
+ assert db.session.get(User, user.id).export_filename_template == "{{date}} {{title}}"
+
+
+def test_account_post_empty_template_saves_null():
+ with app.app_context():
+ user = _mk_user(template="{{title}}")
+ client = app.test_client()
+ _login(client, user)
+ resp = client.post(
+ "/account",
+ data={"export_filename_template": " "},
+ headers={"X-Requested-With": "XMLHttpRequest"},
+ )
+ assert resp.status_code == 200
+ db.session.expire_all()
+ assert db.session.get(User, user.id).export_filename_template is None
+
+
+def test_account_post_rejects_path_separators():
+ with app.app_context():
+ user = _mk_user(template="{{title}}")
+ client = app.test_client()
+ _login(client, user)
+ for bad in ("../{{title}}", "a/b", "a\\b"):
+ resp = client.post(
+ "/account",
+ data={"export_filename_template": bad},
+ headers={"X-Requested-With": "XMLHttpRequest"},
+ )
+ assert resp.status_code == 400
+ db.session.expire_all()
+ # Original template untouched.
+ assert db.session.get(User, user.id).export_filename_template == "{{title}}"
+
+
+if __name__ == "__main__":
+ # Legacy standalone invocation support (mirrors other test files).
+ import pytest
+ sys.exit(pytest.main([__file__, "-v"]))