From eea4e5bdf2e5f3cee8b00c861189f7dee8845c76 Mon Sep 17 00:00:00 2001
From: Christian Bager Bach Houmann <christian@bagerbach.com>
Date: Sun, 23 Nov 2025 21:49:29 +0100
Subject: [PATCH] feat: add timestamp offset setting

---
 src/API/API.ts                         | 12 +++++++++---
 src/API/IAPI.ts                        |  6 +++++-
 src/TemplateEngine.ts                  |  6 ++++--
 src/constants.ts                       |  1 +
 src/main.ts                            |  8 +++++++-
 src/types/IPodNotesSettings.ts         |  1 +
 src/ui/settings/PodNotesSettingsTab.ts | 20 ++++++++++++++++++++
 7 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/src/API/API.ts b/src/API/API.ts
index ef05535..659cfef 100644
--- a/src/API/API.ts
+++ b/src/API/API.ts
@@ -38,14 +38,20 @@ export class API implements IAPI {
 	 * Gets the current time in the given moment format.
 	 * @param format Moment format.
 	 * @param linkify Linking to the podcast so PodNotes can open it at this time later.
+	 * @param offsetSeconds Optional offset to subtract from the current playback time.
 	 * @returns
 	 */
-	getPodcastTimeFormatted(format: string, linkify = false): string {
+	getPodcastTimeFormatted(
+		format: string,
+		linkify = false,
+		offsetSeconds = 0,
+	): string {
 		if (!this.podcast) {
 			throw new Error("No podcast loaded");
 		}
 
-		const time = formatSeconds(this.currentTime, format);
+		const adjustedTime = Math.max(0, this.currentTime - offsetSeconds);
+		const time = formatSeconds(adjustedTime, format);
 
 		if (!linkify) return time;
 
@@ -63,7 +69,7 @@ export class API implements IAPI {
 		const url = encodePodnotesURI(
 			this.podcast.title,
 			feedUrl,
-			this.currentTime
+			adjustedTime,
 		);
 
 		return `[${time}](${url.href})`;
diff --git a/src/API/IAPI.ts b/src/API/IAPI.ts
index db76d96..48f3412 100644
--- a/src/API/IAPI.ts
+++ b/src/API/IAPI.ts
@@ -6,7 +6,11 @@ export interface IAPI {
 	readonly length: number;
 	currentTime: number;
 
-	getPodcastTimeFormatted(format: string, linkify?: boolean): string;
+	getPodcastTimeFormatted(
+		format: string,
+		linkify?: boolean,
+		offsetSeconds?: number,
+	): string;
 	
 	start(): void;
 	stop(): void;
diff --git a/src/TemplateEngine.ts b/src/TemplateEngine.ts
index 6e06064..c3a7a01 100644
--- a/src/TemplateEngine.ts
+++ b/src/TemplateEngine.ts
@@ -117,12 +117,14 @@ export function NoteTemplateEngine(template: string, episode: Episode) {
 
 export function TimestampTemplateEngine(template: string) {
 	const [replacer, addTag] = useTemplateEngine();
+	const { api, settings } = get(plugin);
+	const timestampOffset = settings.timestamp.offset ?? 0;
 
 	addTag("time", (format?: string) =>
-		get(plugin).api.getPodcastTimeFormatted(format ?? "HH:mm:ss"),
+		api.getPodcastTimeFormatted(format ?? "HH:mm:ss", false, timestampOffset),
 	);
 	addTag("linktime", (format?: string) =>
-		get(plugin).api.getPodcastTimeFormatted(format ?? "HH:mm:ss", true),
+		api.getPodcastTimeFormatted(format ?? "HH:mm:ss", true, timestampOffset),
 	);
 
 	return replacer(template);
diff --git a/src/constants.ts b/src/constants.ts
index b0532e7..5d51db2 100644
--- a/src/constants.ts
+++ b/src/constants.ts
@@ -49,6 +49,7 @@ export const DEFAULT_SETTINGS: IPodNotesSettings = {
 
 	timestamp: {
 		template: "- {{time}} ",
+		offset: 0,
 	},
 
 	note: {
diff --git a/src/main.ts b/src/main.ts
index 924bd10..7955843 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -340,7 +340,13 @@ export default class PodNotes extends Plugin implements IPodNotes {
 	}
 
 	async loadSettings() {
-		this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
+		const loadedData = await this.loadData();
+
+		this.settings = Object.assign({}, DEFAULT_SETTINGS, loadedData);
+		this.settings.timestamp = {
+			...DEFAULT_SETTINGS.timestamp,
+			...(loadedData?.timestamp ?? {}),
+		};
 	}
 
 	async saveSettings() {
diff --git a/src/types/IPodNotesSettings.ts b/src/types/IPodNotesSettings.ts
index 611556b..78802cf 100644
--- a/src/types/IPodNotesSettings.ts
+++ b/src/types/IPodNotesSettings.ts
@@ -20,6 +20,7 @@ export interface IPodNotesSettings {
 
 	timestamp: {
 		template: string;
+		offset: number;
 	};
 
 	note: {
diff --git a/src/ui/settings/PodNotesSettingsTab.ts b/src/ui/settings/PodNotesSettingsTab.ts
index 4ef96c7..2336f87 100644
--- a/src/ui/settings/PodNotesSettingsTab.ts
+++ b/src/ui/settings/PodNotesSettingsTab.ts
@@ -160,6 +160,26 @@ export class PodNotesSettingsTab extends PluginSettingTab {
 			);
 		};
 
+		new Setting(container)
+			.setName("Timestamp offset (s)")
+			.setDesc(
+				"Subtract this many seconds when capturing a timestamp to compensate for reaction time.",
+			)
+			.addText((textComponent) => {
+				textComponent.inputEl.type = "number";
+				textComponent
+					.setValue(`${this.plugin.settings.timestamp.offset}`)
+					.onChange((value) => {
+						const parsedValue = Number.parseInt(value, 10);
+						this.plugin.settings.timestamp.offset = Number.isNaN(parsedValue)
+							? 0
+							: Math.max(0, parsedValue);
+						this.plugin.saveSettings();
+						updateTimestampDemo(this.plugin.settings.timestamp.template);
+					})
+					.setPlaceholder("e.g. 5");
+			});
+
 		updateTimestampDemo(this.plugin.settings.timestamp.template);
 
 		const randomEpisode = getRandomEpisode();