Skip to content

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

Python

Filename dates: a time followed by Z is UTC and is not shifted by the browser timezone (#486)

Murtaza Nasirc06706b1ea5b
diff --git a/docs/user-guide/settings.md b/docs/user-guide/settings.md
index 3da8ed9a..81c95ea9 100644
--- a/docs/user-guide/settings.md
+++ b/docs/user-guide/settings.md
@@ -145,7 +145,7 @@ Voice recorders and phone apps commonly encode the recording date in the filenam
The **Filename date format** dropdown offers preset patterns — `YYYYMMDD`, `YYYYMMDD_HHMM`, `YYYY-MM-DD`, `YYMMDD_HHMM`, `YYMMDD` — plus an **Auto** mode that tries the common formats, and a **Custom pattern** option that accepts a regular expression with named groups (`(?P<year>...)`, `(?P<month>...)`, `(?P<day>...)`; `hour` and `minute` are optional). Auto mode deliberately skips the bare six-digit `YYMMDD` form, since any six digits in a filename would qualify; select that preset explicitly if your recorder uses it.
-The setting is off by default. A file whose name contains no matching date keeps the existing behaviour (file timestamps, then upload time) without failing the upload, and the parsed date remains editable afterwards from the recording's details. Dates parsed from filenames are wall-clock times: browser uploads send your timezone so the stored date displays correctly everywhere, and date-only matches are anchored so the calendar date never shifts between viewers. The setting also applies to files dropped into the automated processing folder.
+The setting is off by default. A file whose name contains no matching date keeps the existing behaviour (file timestamps, then upload time) without failing the upload, and the parsed date remains editable afterwards from the recording's details. Dates parsed from filenames are wall-clock times: browser uploads send your timezone so the stored date displays correctly everywhere, and date-only matches are anchored so the calendar date never shifts between viewers. A time followed by `Z`, as in `recording-2026-10-25T11-43-00-000Z.webm` from the browser recorder, is read as UTC. The setting also applies to files dropped into the automated processing folder.
This setting is not the same as **Naming Templates** (Account → Templates), which generate a recording's *title* from template variables and can also extract text from filenames with their own patterns. The two are independent — naming templates never change the meeting date, and this setting never changes the title — but they work together: a naming template's `{{date}}`, `{{year}}`, `{{month}}` and `{{day}}` variables render the recording's meeting date, so with filename parsing enabled, a file named `20260716_call.mp3` and the "Date Prefix" naming template produces a title dated July 16, 2026 rather than the day you uploaded it.
diff --git a/src/utils/filename_dates.py b/src/utils/filename_dates.py
index 34117c69..9c630af5 100644
--- a/src/utils/filename_dates.py
+++ b/src/utils/filename_dates.py
@@ -14,6 +14,8 @@ storage. Callers pass ``tz_offset_minutes`` in JavaScript
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
@@ -58,6 +60,10 @@ 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
@@ -139,6 +145,9 @@ def parse_filename_date(filename: str, pattern_key: str = 'auto',
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
diff --git a/tests/test_filename_dates.py b/tests/test_filename_dates.py
index f008d65b..2e52af18 100644
--- a/tests/test_filename_dates.py
+++ b/tests/test_filename_dates.py
@@ -262,3 +262,33 @@ def test_settings_save_and_validation():
finally:
db.session.delete(user)
db.session.commit()
+
+
+# ===========================================================================
+# UTC-marked times (#486)
+# ===========================================================================
+
+ 'recording-2026-10-25T11-43-00-000Z.webm',
+ 'recording-2026-10-25T11:43:00.000Z.webm',
+ '2026-10-25T11-43Z.mp3',
+ '20261025_1143Z.m4a',
+])
+def test_utc_suffix_is_not_shifted(name):
+ expected = datetime(2026, 10, 25, 11, 43)
+ assert parse_filename_date(name, 'auto', tz_offset_minutes=-480) == expected
+ assert parse_filename_date(name, 'auto', tz_name='Asia/Shanghai') == expected
+
+
+def test_local_time_without_suffix_still_shifted():
+ assert parse_filename_date('recording-2026-10-25T19-43-00.webm', 'auto',
+ tz_name='Asia/Shanghai') == datetime(2026, 10, 25, 11, 43)
+
+
+def test_z_starting_a_word_is_not_utc():
+ assert parse_filename_date('2026-10-25 1143 Zoom call.mp3', 'auto',
+ tz_offset_minutes=-480) == datetime(2026, 10, 25, 3, 43)
+
+
+def test_date_only_with_z_keeps_noon_anchor():
+ assert parse_filename_date('2026-10-25Z.mp3', 'auto') == datetime(2026, 10, 25, 12, 0)