Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
"""
Parse meeting dates out of uploaded filenames (#342).
Voice recorders and phone apps commonly encode the recording date in the
filename (``20260716_meeting.mp3``, ``260716_1102.m4a``). When a user
enables filename date parsing, the date found here takes precedence over
file metadata / browser lastModified when setting ``meeting_date``.
Timezone semantics: a filename date is a *wall-clock* value in the
uploader's local timezone. ``meeting_date`` is stored as naive UTC and
rendered viewer-local, so the parsed value must be shifted to UTC before
storage. Callers pass ``tz_offset_minutes`` in JavaScript
``getTimezoneOffset()`` convention (minutes to ADD to local time to get
UTC; positive west of UTC). When no offset is known, date-only matches
are anchored at 12:00 UTC so the calendar date survives rendering in any
viewer timezone, and time-bearing matches are treated as already UTC.
A time followed by a ``Z`` suffix (an ISO 8601 UTC time, as in the names of
Speakr's own browser recordings) is UTC already and is not shifted (#486).
"""
import re
from datetime import datetime, timedelta
from typing import Optional
# Presets are matched against the filename stem (extension stripped).
# Digit lookarounds stop a longer digit run (e.g. a phone number) from
# donating a spurious "date". Order within AUTO_PRESET_ORDER runs the most
# specific patterns first.
PRESET_PATTERNS = {
# 20260716_1102, 20260716-1102, "20260716 1102"
'yyyymmdd_hhmm': re.compile(
r'(?<!\d)(?P<year>(?:19|20)\d{2})(?P<month>\d{2})(?P<day>\d{2})'
r'[_\- ](?P<hour>\d{2})[:.]?(?P<minute>\d{2})(?!\d)'
),
# 2026-07-16, 2026_07_16, 2026.07.16, optionally followed by 11-02 / 11:02 / 1102
'yyyy-mm-dd': re.compile(
r'(?<!\d)(?P<year>(?:19|20)\d{2})[-_.](?P<month>\d{2})[-_.](?P<day>\d{2})'
r'(?:[_\- T](?P<hour>\d{2})[:.\-_]?(?P<minute>\d{2})(?!\d))?'
),
# 20260716
'yyyymmdd': re.compile(
r'(?<!\d)(?P<year>(?:19|20)\d{2})(?P<month>\d{2})(?P<day>\d{2})(?!\d)'
),
# 260716_1102
'yymmdd_hhmm': re.compile(
r'(?<!\d)(?P<year>\d{2})(?P<month>\d{2})(?P<day>\d{2})'
r'[_\- ](?P<hour>\d{2})[:.]?(?P<minute>\d{2})(?!\d)'
),
# 260716 — ambiguous six digits; only used when explicitly selected,
# never as part of 'auto' (see AUTO_PRESET_ORDER).
'yymmdd': re.compile(
r'(?<!\d)(?P<year>\d{2})(?P<month>\d{2})(?P<day>\d{2})(?!\d)'
),
}
# 'auto' tries these in order. Bare yymmdd is excluded: any six digits in
# a filename would qualify, which produces far too many false positives.
AUTO_PRESET_ORDER = ('yyyymmdd_hhmm', 'yyyy-mm-dd', 'yyyymmdd', 'yymmdd_hhmm')
VALID_PATTERN_KEYS = ('auto',) + tuple(PRESET_PATTERNS.keys()) + ('custom',)
# Optional seconds and fraction, then the ISO 8601 "Z" marker, right after
# the matched time: 11-43-00-000Z, 11:43:00.000Z, 1143Z.
_UTC_SUFFIX = re.compile(r'(?:[-:._]?\d{2}(?:[-.,]\d{1,9})?)?Z(?![A-Za-z])')
_MIN_YEAR = 1970
_MAX_YEAR = 2100
def _build_datetime(groups) -> Optional[datetime]:
"""Turn named regex groups into a validated datetime, or None."""
try:
year = int(groups['year'])
if year < 100:
year += 2000
month = int(groups['month'])
day = int(groups['day'])
hour = int(groups.get('hour') or 0)
minute = int(groups.get('minute') or 0)
except (KeyError, TypeError, ValueError):
return None
if not (_MIN_YEAR <= year <= _MAX_YEAR):
return None
if hour > 23 or minute > 59:
return None
try:
return datetime(year, month, day, hour, minute)
except ValueError:
return None
def _has_time(groups) -> bool:
return bool(groups.get('hour'))
def parse_filename_date(filename: str, pattern_key: str = 'auto',
custom_regex: Optional[str] = None,
tz_offset_minutes: Optional[int] = None,
tz_name: Optional[str] = None) -> Optional[datetime]:
"""
Extract a meeting date from *filename* and return it as naive UTC.
Args:
filename: Original filename (extension is stripped before matching).
pattern_key: One of VALID_PATTERN_KEYS.
custom_regex: Required when pattern_key == 'custom'. Must define
named groups ``year``, ``month``, ``day`` and may define
``hour`` and ``minute``.
tz_offset_minutes: JavaScript getTimezoneOffset() value for the
uploader (minutes to add to local time to reach UTC). None
when the client timezone is unknown.
Returns:
Naive-UTC datetime, or None when nothing (valid) matched. Never
raises: a broken custom regex simply yields None.
"""
if not filename:
return None
stem = filename.rsplit('.', 1)[0] if '.' in filename else filename
candidates = []
if pattern_key == 'auto':
candidates = [PRESET_PATTERNS[k] for k in AUTO_PRESET_ORDER]
elif pattern_key in PRESET_PATTERNS:
candidates = [PRESET_PATTERNS[pattern_key]]
elif pattern_key == 'custom' and custom_regex:
try:
candidates = [re.compile(custom_regex)]
except re.error:
return None
else:
return None
for pattern in candidates:
try:
match = pattern.search(stem)
except Exception:
continue
if not match:
continue
groups = match.groupdict()
parsed = _build_datetime(groups)
if parsed is None:
continue
if _has_time(groups) and _UTC_SUFFIX.match(stem, match.end()):
return parsed
# Local wall-clock -> naive UTC per the storage convention. A named zone
# (the browser's IANA zone) gives the offset that applied on that date,
# across daylight-saving changes; the browser's current offset is the
# fallback (#412 B9).
if tz_name:
from src.utils.timezones import is_valid_timezone
if is_valid_timezone(tz_name):
from zoneinfo import ZoneInfo
from datetime import timezone as _utc
return parsed.replace(tzinfo=ZoneInfo(tz_name)).astimezone(_utc.utc).replace(tzinfo=None)
if tz_offset_minutes is not None:
try:
offset = int(tz_offset_minutes)
except (TypeError, ValueError):
offset = None
# Sanity-bound the offset to real-world values (UTC-12..UTC+14).
if offset is not None and -14 * 60 <= offset <= 12 * 60:
return parsed + timedelta(minutes=offset)
if not _has_time(groups):
# Date-only with unknown timezone: anchor at 12:00 UTC so the
# calendar date renders unchanged in any viewer timezone.
return parsed.replace(hour=12, minute=0)
return parsed
return None
def validate_custom_regex(custom_regex: str) -> Optional[str]:
"""
Validate a user-supplied custom regex. Returns an error message string
in the interface language (#477), or None when the regex is acceptable.
"""
from src.utils.localization import translate
if not custom_regex or not custom_regex.strip():
return translate('server.apiError.custom_date_pattern_required')
if len(custom_regex) > 500:
return translate('server.apiError.custom_date_pattern_too_long')
try:
compiled = re.compile(custom_regex)
except re.error as e:
return translate('server.apiError.invalid_regular_expression', detail=str(e))
required = {'year', 'month', 'day'}
missing = required - set(compiled.groupindex.keys())
if missing:
return translate('server.apiError.custom_date_pattern_missing_groups',
groups=', '.join(sorted(missing)))
return None