I record my lectures. Then, for the rest of the semester, I scroll through a
folder of files called something like 20261020_141502.m4a, trying to
remember which one was the Tuesday lecture where the professor finally
explained the thing.
The information is all there. My academics calendar knows when each lecture
was. The phone knows when each recording was made. Nothing was joining the
two.
So that’s what this week was. It was much quieter than last week: thirteen
commits, all on Tuesday and Wednesday, and twelve of them are one new
service. It’s called recording-linker, and its job fits in a sentence: when
a recording lands in Nextcloud, attach it to the calendar event it was made
in.
Tuesday: the whole thing, in one evening
The first commit was big, about 600 lines of Python. It’s a stateless poller, running as a single container on the Pi with no ports open. Every 60 seconds it looks in a Nextcloud Files folder, the one the phone auto-uploads to, and works through what’s there.
When did this recording happen?
That turns out to be the interesting question.
If the file name has a date and time in it (most recorders write one), that’s the start, and the duration comes from the file’s own headers. I use mutagen to read them, through HTTP Range requests, so the service reads a few hundred KB of an hour-long lecture instead of downloading the whole thing. That matters for m4a in particular, where the part that holds the duration can sit at the very end of the file.
No time in the name? Then it falls back to the file’s modification time. The Nextcloud clients upload with the phone’s own mtime, so even if the upload happens three hours later on Wi-Fi, the server still knows when the phone finished writing the file. And if there’s no readable duration at all, the recording is treated as a single instant at its end.
Which event?
Of the timed events in the calendar, the one the recording overlaps most. Each event gets stretched 15 minutes before its start and 30 after its end, because I never press record exactly on time and I always forget to stop. All-day and cancelled events never match.
Repeating events are expanded by the service itself, with recurring-ical-events, not by the server. Servers don’t agree on how to do it: Radicale’s version drops events that don’t repeat.
Attaching it
This is the part I cared about most. The service writes exactly the same
ATTACH property the Nextcloud Calendar app writes when you pick a file
from Files yourself: the content type, the file name, Nextcloud’s file id,
and a /f/<fileid> link. To the Calendar app it should look like I attached
it by hand.
On a weekly lecture, the attachment goes on that one occurrence, through
an override with a RECURRENCE-ID, never on the whole series. Otherwise
every Tuesday of the semester would carry the same recording. The write is
conditional (If-Match), so if I edit the event at the same moment, the
service backs off and tries again on the next poll.
Then the file moves to Attached. The file id survives the move, so the link
keeps working. A recording with no match waits an hour, in case I add the
event late, and then goes to Unmatched.
Two rules I’m glad I wrote down early:
- Events with attendees are never touched. Nextcloud would email every
attendee about the change. Nobody needs a notification that I attached
20261020_141502.m4ato a meeting. If such an event is the best match, the file counts as unmatched, rather than landing on the wrong neighbour. - No state. The watch folder is the inbox. To retry a file, move it back in. A file that was already attached (say, the container stopped between attaching and moving) only gets moved, never attached twice.
Before any of it touched the Pi, I tested it end to end against Radicale 3.8
and a fake of Nextcloud’s Files WebDAV, with real 80–85 minute AAC and MP3
files made with ffmpeg. Adjacent lectures, a weekly lecture across the
October clock change, an event with attendees, an unreadable file, a name
clash in Attached. It passed.
Then the real calendar
Two minutes after that first commit came the first fix, and it came from my actual timetable, not the fake one.
My lectures sit back to back, 15 minutes apart. With the 15/30 stretch, a recording known only by its end can fall inside two windows at once. One ending at 10:40 was going to the 10:45 lecture, because ties went to the event with the closest start. It belonged to the 08:45–10:30 one. Ties now compare start to start and end to end.
The test suite looked fine. The real calendar wasn’t. That happens a lot.
Dry run
Next came encrypted env files for the Pi and a first deploy with
DRY_RUN=true: it logs what it would do, and changes nothing.
It went unhealthy straight away. A dry run doesn’t create the watch folder, and before the phone’s first upload that folder doesn’t exist. So the service logged a 404 every minute, never wrote its heartbeat, and Docker marked it unhealthy. A missing folder now means “nothing to do yet”: logged once, and the poll counts as a success.
The dry run was also noisy. It sees the same files every minute, so it said “would move” about each one every minute. Now each file’s outcome is logged once per process, and a file still waiting for its event says when it will be checked again.
The recorder problem
My phone’s recorder at the time could only save to Downloads, with names like
20.10.2026 19.52.51.m4a. Day first. And Downloads holds a lot of other
things I didn’t want a script moving around.
So I added a second source: a pickup folder plus a pattern, where only files whose whole name matches get moved into the watch folder, and day-first times get parsed too. It worked. It was also clearly a workaround for one app.
Wednesday: delete the workaround
The next afternoon the service went live, DRY_RUN=false. That’s after the
dry run had matched my first real lecture recording to the right event.
And then I changed the recorder instead of the code. The phone now records
with Fossify Voice Recorder, into its own folder, which the
Nextcloud app auto-uploads straight to
/Recordings/Temporary. Year-first names, 20261021_091510.m4a. No
Downloads, no pattern matching.
So the pickup folder and the day-first parsing came out again, a day after they went in: 114 lines deleted, 62 added. I like commits like that. The best fix for a strange input is often to stop getting the strange input.
Late Wednesday: a permissions bug that had always been there
The last commit of the week isn’t about recordings at all.
I also run File Browser on the Pi, on the same shared disk that Nextcloud mounts as an external storage. Everything uploaded through File Browser showed up in Nextcloud as “Permission denied”. Every file.
The image ran as uid 911 by default, and File Browser creates files 0640
and folders 0750. Nextcloud runs as www-data, uid 33, so it was locked
out of everything File Browser had ever written. The fix is two environment
variables, PUID and PGID set to 33, so both apps write as the same user.
Then the cleanup on the Pi: the data directory chowned to 33:33 (the image’s
init doesn’t do it), and 357 existing files owned by uid 911 under the shared
folder chowned to 33:33.
357 files that one of my own apps couldn’t open, sitting on my own disk. That one stings a little.
What’s still open
The README is honest about this, so I will be too: three things are still
unverified against the live services. Nextcloud’s upload-time property, the
MOVE, and whether the attachment actually shows up in the Calendar app the
way a hand-picked one does. The service is live, and the dry run matched the
right lecture. Seeing it show up on the event is next week’s check.
The takeaway
The most useful thing I built this week wasn’t clever. Two systems I already ran each held half of the answer, and a small script that joins them saves me more time than anything I tuned last week.
So look at your own setup for that. Two apps that each know half of something. A calendar and a folder. A photo’s timestamp and a trip. The glue between them is often a single evening’s work, and it pays you back every week after.
Sources
- Nextcloud Calendar and the Nextcloud Android app’s auto upload
- RFC 5545 (iCalendar), on
ATTACHandRECURRENCE-ID, and RFC 4791 (CalDAV) - recurring-ical-events, icalendar and mutagen
- Radicale, the CalDAV server used for testing
- Fossify Voice Recorder
- File Browser
- The commit history of my homelab repo, 20–21 October 2026