From f68b8811fcd645450f1754ecf482c4a2c6ce663e Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 2 Sep 2026 08:53:00 +0000
Subject: [PATCH 1/8] feat(web-player): copy media links with middle-click

Middle-click a channel to copy its live URL, or a program to copy the
catch-up URL for that timeslot, then show a toast on success.

Co-authored-by: Stackie Jia <jsq2627@gmail.com>
---
 .../references/translation-memory.md          |   1 +
 docs/en/guide/web-player.md                   |  10 +
 docs/guide/web-player.md                      |  10 +
 .../components/player/channel-list-item.tsx   |  23 +-
 web-ui/src/components/player/channel-list.tsx |   6 +
 web-ui/src/components/player/epg-view.tsx     |  37 ++-
 web-ui/src/components/player/player-toast.tsx |  56 ++++
 web-ui/src/i18n/player.ts                     |  12 +
 web-ui/src/lib/catchup-url.test.ts            |  43 +++
 web-ui/src/lib/catchup-url.ts                 | 272 +++++++++++++++++
 web-ui/src/lib/clipboard.ts                   |  30 ++
 web-ui/src/lib/m3u-parser.test.ts             |  32 ++
 web-ui/src/lib/m3u-parser.ts                  | 283 +-----------------
 web-ui/src/lib/media-direct-link.test.ts      |  97 ++++++
 web-ui/src/lib/media-direct-link.ts           | 102 +++++++
 web-ui/src/pages/player.tsx                   |  45 ++-
 16 files changed, 775 insertions(+), 284 deletions(-)
 create mode 100644 web-ui/src/components/player/player-toast.tsx
 create mode 100644 web-ui/src/lib/catchup-url.test.ts
 create mode 100644 web-ui/src/lib/catchup-url.ts
 create mode 100644 web-ui/src/lib/clipboard.ts
 create mode 100644 web-ui/src/lib/m3u-parser.test.ts
 create mode 100644 web-ui/src/lib/media-direct-link.test.ts
 create mode 100644 web-ui/src/lib/media-direct-link.ts

diff --git a/.agents/skills/translate-docs-zh-en/references/translation-memory.md b/.agents/skills/translate-docs-zh-en/references/translation-memory.md
index 335d5446..c7e92518 100644
--- a/.agents/skills/translate-docs-zh-en/references/translation-memory.md
+++ b/.agents/skills/translate-docs-zh-en/references/translation-memory.md
@@ -17,6 +17,7 @@
 - 快速换台 -> fast channel change / channel switching
 - 无缝换台 -> seamless channel switching / Seamless switch (player setting label)
 - 时移回看 -> time-shifted playback / time-shift / catch-up
+- 媒体直链 -> media link / direct media URL
 - 电子节目单 -> EPG (Electronic Program Guide)
 - 频道 -> channel
 - 线路/源 -> source
diff --git a/docs/en/guide/web-player.md b/docs/en/guide/web-player.md
index 66f1ec65..71cf1ba0 100644
--- a/docs/en/guide/web-player.md
+++ b/docs/en/guide/web-player.md
@@ -29,9 +29,19 @@ http://server:port/player#CCTV-1
 
 The player automatically updates the address bar when you switch channels, so you can copy the link at any time to share the channel currently playing.
 
+## Copy Media Links
+
+Middle-click a channel in the channel list to copy that channel's live URL for the current source. Middle-click a program in the program guide to copy that program's catch-up URL (the channel must have `catchup-source` configured). A toast appears after a successful copy.
+
+The copied value is a directly requestable HTTP media URL, which you can download with FFmpeg, N_m3u8DL-RE, IDM, or open in a third-party player. For multi-source channels, the most recently used source is copied. If the current page includes `r2h-token`, the copied link includes that parameter as well.
+
+> [!NOTE]
+> An on-air program with no catch-up source copies the live URL. A program that has not started and has no catch-up source cannot be copied.
+
 ## Features
 
 - **Channel List**: Automatically loads configured M3U channel lists
+- **Copy Media Links**: Middle-click a channel or program to copy its live or catch-up URL
 - **Live Streaming**: Watch live broadcasts directly in the browser
 - **Time-Shifted Playback**: Supports EPG (Electronic Program Guide) and time-shifted playback (requires catchup source)
 - **Fast Startup**: Achieves millisecond-level channel switching with FCC
diff --git a/docs/guide/web-player.md b/docs/guide/web-player.md
index 94f721eb..c2819607 100644
--- a/docs/guide/web-player.md
+++ b/docs/guide/web-player.md
@@ -29,9 +29,19 @@ http://服务器地址:端口/player#CCTV-1
 
 播放器在切换频道时会自动更新地址栏，随时复制即可分享当前正在播放的频道。
 
+## 复制媒体直链
+
+在频道列表中键点击频道，可复制该频道当前线路的直播地址。在节目单中键点击节目，可复制该节目的回看地址（需要频道配置了 `catchup-source`）。复制成功后页面会弹出提示。
+
+复制得到的是可直接请求的 HTTP 媒体地址，可用于 FFmpeg、N_m3u8DL-RE、IDM 等工具下载或在第三方播放器中打开。多线路频道会复制最近一次使用的线路；若当前页面带有 `r2h-token`，复制的链接也会带上该参数。
+
+> [!NOTE]
+> 正在播出且没有回看源的节目会复制直播地址。尚未开始且没有回看源的节目无法复制。
+
 ## 功能特性
 
 - **频道列表**：自动加载配置的 M3U 频道列表
+- **复制媒体直链**：中键点击频道或节目，复制直播或回看地址
 - **在线直播**：在浏览器中直接观看直播
 - **时移回看**：支持 EPG 电子节目单和时移回看（需要有回看源）
 - **快速起播**：搭配 FCC 可实现毫秒级换台速度
diff --git a/web-ui/src/components/player/channel-list-item.tsx b/web-ui/src/components/player/channel-list-item.tsx
index 804d4878..01a5a7ca 100644
--- a/web-ui/src/components/player/channel-list-item.tsx
+++ b/web-ui/src/components/player/channel-list-item.tsx
@@ -1,8 +1,9 @@
 import { clsx } from "clsx";
 import { History } from "lucide-react";
-import { forwardRef, memo, useCallback } from "react";
+import { forwardRef, memo, type MouseEvent as ReactMouseEvent, useCallback } from "react";
 import { usePlayerTranslation } from "../../hooks/use-player-translation";
 import type { Locale } from "../../lib/locale";
+import { isMiddleMouseButton } from "../../lib/media-direct-link";
 import type { Channel } from "../../types/player";
 import {
   PLAYER_CHANNEL_LIST_ITEM_CLASS,
@@ -17,12 +18,13 @@ interface ChannelListItemProps {
   channel: Channel;
   isCurrentChannel: boolean;
   handleChannelClick: (channel: Channel) => void;
+  onCopyMediaLink: (channel: Channel) => void;
   locale: Locale;
   currentProgram?: string;
 }
 
 const ChannelListItemComponent = forwardRef<HTMLButtonElement, ChannelListItemProps>(
-  ({ channel, isCurrentChannel, handleChannelClick, locale, currentProgram }, ref) => {
+  ({ channel, isCurrentChannel, handleChannelClick, onCopyMediaLink, locale, currentProgram }, ref) => {
     const t = usePlayerTranslation(locale);
     const groupLabel = channel.groups.join(" / ");
 
@@ -30,11 +32,26 @@ const ChannelListItemComponent = forwardRef<HTMLButtonElement, ChannelListItemPr
       handleChannelClick(channel);
     }, [handleChannelClick, channel]);
 
+    const handleMouseDown = useCallback((event: ReactMouseEvent<HTMLButtonElement>) => {
+      if (isMiddleMouseButton(event)) event.preventDefault();
+    }, []);
+
+    const handleAuxClick = useCallback(
+      (event: ReactMouseEvent<HTMLButtonElement>) => {
+        if (!isMiddleMouseButton(event)) return;
+        event.preventDefault();
+        event.stopPropagation();
+        onCopyMediaLink(channel);
+      },
+      [channel, onCopyMediaLink],
+    );
+
     return (
       <button
         type="button"
         key={channel.id}
         ref={ref}
+        title={t("copyMediaLinkHint")}
         className={clsx(
           PLAYER_LIST_SURFACE_BASE_CLASS,
           PLAYER_CHANNEL_LIST_ITEM_CLASS,
@@ -43,6 +60,8 @@ const ChannelListItemComponent = forwardRef<HTMLButtonElement, ChannelListItemPr
           !isCurrentChannel && PLAYER_LIST_SURFACE_HOVER_CLASS,
         )}
         onClick={handleClick}
+        onMouseDown={handleMouseDown}
+        onAuxClick={handleAuxClick}
       >
         <PlayerSelectedGlassLayers visible={isCurrentChannel} />
         {/* Left: Channel Number and Info */}
diff --git a/web-ui/src/components/player/channel-list.tsx b/web-ui/src/components/player/channel-list.tsx
index 3bacfb67..882da383 100644
--- a/web-ui/src/components/player/channel-list.tsx
+++ b/web-ui/src/components/player/channel-list.tsx
@@ -13,6 +13,7 @@ interface ChannelListProps {
   groups?: string[];
   currentChannel: Channel | null;
   onChannelSelect: (channel: Channel) => void;
+  onCopyMediaLink: (channel: Channel) => void;
   locale: Locale;
   settingsSlot?: React.ReactNode;
   epgData?: EPGData;
@@ -54,6 +55,7 @@ interface ChannelListResultsProps {
   filteredChannels: Channel[];
   filteredChannelsHasCurrentChannel: boolean;
   handleChannelClick: (channel: Channel) => void;
+  onCopyMediaLink: (channel: Channel) => void;
   locale: Locale;
 }
 
@@ -64,6 +66,7 @@ const ChannelListResults = memo(function ChannelListResults({
   filteredChannels,
   filteredChannelsHasCurrentChannel,
   handleChannelClick,
+  onCopyMediaLink,
   locale,
 }: ChannelListResultsProps) {
   return (
@@ -79,6 +82,7 @@ const ChannelListResults = memo(function ChannelListResults({
           channel={channel}
           isCurrentChannel={channel.id === currentChannel?.id}
           handleChannelClick={handleChannelClick}
+          onCopyMediaLink={onCopyMediaLink}
           locale={locale}
           currentProgram={currentProgramMap[channel.id]}
         />
@@ -92,6 +96,7 @@ function ChannelListComponent({
   groups,
   currentChannel,
   onChannelSelect,
+  onCopyMediaLink,
   locale,
   settingsSlot,
   epgData,
@@ -249,6 +254,7 @@ function ChannelListComponent({
           filteredChannels={filteredChannels}
           filteredChannelsHasCurrentChannel={Boolean(filteredChannelsHasCurrentChannel)}
           handleChannelClick={handleChannelClick}
+          onCopyMediaLink={onCopyMediaLink}
           locale={locale}
         />
       </div>
diff --git a/web-ui/src/components/player/epg-view.tsx b/web-ui/src/components/player/epg-view.tsx
index 4bfe3802..7ddd0cb0 100644
--- a/web-ui/src/components/player/epg-view.tsx
+++ b/web-ui/src/components/player/epg-view.tsx
@@ -1,10 +1,20 @@
 import { clsx } from "clsx";
 import { Circle, History } from "lucide-react";
-import { memo, type RefObject, useCallback, useDeferredValue, useLayoutEffect, useMemo, useRef } from "react";
+import {
+  memo,
+  type MouseEvent as ReactMouseEvent,
+  type RefObject,
+  useCallback,
+  useDeferredValue,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from "react";
 import { usePlayerTranslation } from "../../hooks/use-player-translation";
 import { useWallClockMinute } from "../../hooks/use-wall-clock-minute";
 import type { EPGData } from "../../lib/epg-parser";
 import type { Locale } from "../../lib/locale";
+import { isMiddleMouseButton } from "../../lib/media-direct-link";
 import type { EPGProgram } from "../../types/player";
 import {
   PLAYER_EPG_LIST_ITEM_CLASS,
@@ -19,6 +29,7 @@ interface EPGViewProps {
   channelId: string | null;
   epgData: EPGData;
   onProgramSelect: (programStart: Date, programEnd: Date) => void;
+  onCopyMediaLink: (program: EPGProgram) => void;
   locale: Locale;
   supportsCatchup: boolean;
   currentPlayingProgram: EPGProgram | null;
@@ -48,6 +59,7 @@ interface EPGProgramItemProps {
   currentProgramRef: RefObject<HTMLButtonElement | null>;
   durationMinutes: number;
   handleProgramClick: (programStart: Date, programEnd: Date) => void;
+  onCopyMediaLink: (program: EPGProgram) => void;
   isPast: boolean;
   locale: Locale;
   onAir: boolean;
@@ -61,6 +73,7 @@ const EPGProgramItem = memo(function EPGProgramItem({
   currentProgramRef,
   durationMinutes,
   handleProgramClick,
+  onCopyMediaLink,
   isPast,
   locale,
   onAir,
@@ -71,10 +84,25 @@ const EPGProgramItem = memo(function EPGProgramItem({
 }: EPGProgramItemProps) {
   const t = usePlayerTranslation(locale);
 
+  const handleMouseDown = useCallback((event: ReactMouseEvent<HTMLButtonElement>) => {
+    if (isMiddleMouseButton(event)) event.preventDefault();
+  }, []);
+
+  const handleAuxClick = useCallback(
+    (event: ReactMouseEvent<HTMLButtonElement>) => {
+      if (!isMiddleMouseButton(event)) return;
+      event.preventDefault();
+      event.stopPropagation();
+      onCopyMediaLink(program);
+    },
+    [onCopyMediaLink, program],
+  );
+
   return (
     <button
       type="button"
       ref={playing ? currentProgramRef : null}
+      title={t("copyMediaLinkHint")}
       className={clsx(
         PLAYER_LIST_SURFACE_BASE_CLASS,
         PLAYER_EPG_LIST_ITEM_CLASS,
@@ -83,6 +111,8 @@ const EPGProgramItem = memo(function EPGProgramItem({
         ((isPast && supportsCatchup) || onAir) && "cursor-pointer",
         !playing && ((isPast && supportsCatchup) || onAir) && PLAYER_LIST_SURFACE_HOVER_CLASS,
       )}
+      onMouseDown={handleMouseDown}
+      onAuxClick={handleAuxClick}
       onClick={() => {
         if (isPast && supportsCatchup) {
           handleProgramClick(program.start, program.end);
@@ -178,6 +208,7 @@ interface EPGDateSectionProps {
   currentProgramRef: RefObject<HTMLButtonElement | null>;
   currentTimeMs: number;
   handleProgramClick: (programStart: Date, programEnd: Date) => void;
+  onCopyMediaLink: (program: EPGProgram) => void;
   locale: Locale;
   section: EPGDateSectionData;
   supportsCatchup: boolean;
@@ -189,6 +220,7 @@ const EPGDateSection = memo(function EPGDateSection({
   currentProgramRef,
   currentTimeMs,
   handleProgramClick,
+  onCopyMediaLink,
   locale,
   section,
   supportsCatchup,
@@ -210,6 +242,7 @@ const EPGDateSection = memo(function EPGDateSection({
               currentProgramRef={currentProgramRef}
               durationMinutes={durationMinutes}
               handleProgramClick={handleProgramClick}
+              onCopyMediaLink={onCopyMediaLink}
               isPast={program.end.getTime() <= currentTimeMs}
               locale={locale}
               onAir={program.start.getTime() <= currentTimeMs && program.end.getTime() > currentTimeMs}
@@ -229,6 +262,7 @@ function EPGViewComponent({
   channelId,
   epgData,
   onProgramSelect,
+  onCopyMediaLink,
   locale,
   supportsCatchup,
   currentPlayingProgram,
@@ -324,6 +358,7 @@ function EPGViewComponent({
             currentProgramRef={currentProgramRef}
             currentTimeMs={currentTimeMs}
             handleProgramClick={handleProgramClick}
+            onCopyMediaLink={onCopyMediaLink}
             locale={locale}
             section={section}
             supportsCatchup={supportsCatchup}
diff --git a/web-ui/src/components/player/player-toast.tsx b/web-ui/src/components/player/player-toast.tsx
new file mode 100644
index 00000000..8fc55c77
--- /dev/null
+++ b/web-ui/src/components/player/player-toast.tsx
@@ -0,0 +1,56 @@
+import { clsx } from "clsx";
+import { CircleAlert, CircleCheck } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export type PlayerToastVariant = "success" | "error";
+
+export interface PlayerToastState {
+  id: number;
+  message: string;
+  variant: PlayerToastVariant;
+}
+
+const TOAST_DURATION_MS = 2500;
+
+export function usePlayerToast() {
+  const [toast, setToast] = useState<PlayerToastState | null>(null);
+  const timerRef = useRef<number>(undefined);
+
+  const showToast = useCallback((message: string, variant: PlayerToastVariant = "success") => {
+    window.clearTimeout(timerRef.current);
+    setToast({ id: Date.now(), message, variant });
+    timerRef.current = window.setTimeout(() => setToast(null), TOAST_DURATION_MS);
+  }, []);
+
+  useEffect(() => () => window.clearTimeout(timerRef.current), []);
+
+  return { toast, showToast };
+}
+
+export function PlayerToast({ toast }: { toast: PlayerToastState | null }) {
+  if (!toast) return null;
+
+  const isSuccess = toast.variant === "success";
+  const Icon = isSuccess ? CircleCheck : CircleAlert;
+
+  return (
+    <div
+      key={toast.id}
+      role="status"
+      aria-live="polite"
+      className="pointer-events-none absolute inset-x-0 bottom-[max(1.25rem,env(safe-area-inset-bottom))] z-[80] flex justify-center px-4"
+    >
+      <div
+        className={clsx(
+          "player-performance-overlay-background player-performance-effect flex max-w-[min(24rem,calc(100vw-2rem))] items-center gap-2 rounded-2xl border px-3.5 py-2.5 text-sm font-medium shadow-[0_16px_40px_-18px_rgba(15,23,42,0.55)] backdrop-blur-xl",
+          isSuccess
+            ? "border-blue-300/40 bg-[linear-gradient(145deg,rgba(239,246,255,0.94),rgba(238,242,255,0.9))] text-blue-800 dark:border-blue-300/20 dark:bg-[linear-gradient(145deg,rgba(15,32,64,0.94),rgba(30,27,75,0.9))] dark:text-blue-100"
+            : "border-rose-300/40 bg-[linear-gradient(145deg,rgba(255,241,242,0.94),rgba(255,228,230,0.9))] text-rose-800 dark:border-rose-300/20 dark:bg-[linear-gradient(145deg,rgba(64,15,32,0.94),rgba(75,27,45,0.9))] dark:text-rose-100",
+        )}
+      >
+        <Icon className="h-4 w-4 shrink-0" />
+        <span className="min-w-0 break-words">{toast.message}</span>
+      </div>
+    </div>
+  );
+}
diff --git a/web-ui/src/i18n/player.ts b/web-ui/src/i18n/player.ts
index 46c4d918..b6371b54 100644
--- a/web-ui/src/i18n/player.ts
+++ b/web-ui/src/i18n/player.ts
@@ -22,6 +22,10 @@ const base: TranslationDict = {
   allChannels: "All",
   catchup: "Catchup",
   catchupSupported: "Catchup supported",
+  copyMediaLinkHint: "Middle-click to copy the media link",
+  mediaLinkCopied: "Media link copied",
+  copyMediaLinkFailed: "Could not copy the media link",
+  copyMediaLinkUnavailable: "No media link available for this item",
 
   // EPG view
   noEpgAvailable: "No program guide available for this channel",
@@ -151,6 +155,10 @@ const zhHans: TranslationDict = {
   allChannels: "全部",
   catchup: "回看",
   catchupSupported: "支持回看",
+  copyMediaLinkHint: "中键点击复制媒体直链",
+  mediaLinkCopied: "已复制媒体直链",
+  copyMediaLinkFailed: "复制媒体直链失败",
+  copyMediaLinkUnavailable: "该项没有可复制的媒体直链",
 
   // EPG 视图
   noEpgAvailable: "此频道暂无节目单",
@@ -280,6 +288,10 @@ const zhHant: TranslationDict = {
   allChannels: "全部",
   catchup: "回看",
   catchupSupported: "支援回看",
+  copyMediaLinkHint: "中鍵點擊複製媒體直鏈",
+  mediaLinkCopied: "已複製媒體直鏈",
+  copyMediaLinkFailed: "複製媒體直鏈失敗",
+  copyMediaLinkUnavailable: "該項沒有可複製的媒體直鏈",
 
   // EPG 視圖
   noEpgAvailable: "此頻道暫無節目表",
diff --git a/web-ui/src/lib/catchup-url.test.ts b/web-ui/src/lib/catchup-url.test.ts
new file mode 100644
index 00000000..aa627654
--- /dev/null
+++ b/web-ui/src/lib/catchup-url.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import type { Source } from "../types/player";
+import { buildCatchupUrl } from "./catchup-url";
+
+const NOW = new Date("2026-09-02T12:00:00.000Z");
+const START = new Date("2026-09-02T10:00:00.000Z");
+const END = new Date("2026-09-02T11:30:00.000Z");
+
+const defaultSource: Source = {
+  url: "http://live.example/ch",
+  catchup: "default",
+  catchupSource: "http://catchup.example/ch?playseek=${utc:yyyyMMddHHmmss}-${utcend:yyyyMMddHHmmss}",
+};
+
+describe("buildCatchupUrl", () => {
+  it("fills UTC playseek placeholders in default mode", () => {
+    expect(buildCatchupUrl(defaultSource, START, END, NOW)).toBe(
+      "http://catchup.example/ch?playseek=20260902100000-20260902113000",
+    );
+  });
+
+  it("appends the filled template onto the live URL in append mode", () => {
+    const source: Source = {
+      url: "http://live.example/ch",
+      catchup: "append",
+      catchupSource: "/catchup?playseek=${(b)yyyyMMddHHmmss|UTC}-${(e)yyyyMMddHHmmss|UTC}",
+    };
+    expect(buildCatchupUrl(source, START, END, NOW)).toBe(
+      "http://live.example/ch/catchup?playseek=20260902100000-20260902113000",
+    );
+  });
+
+  it("substitutes duration in seconds", () => {
+    const source: Source = {
+      url: "http://live.example/ch",
+      catchup: "default",
+      catchupSource: "http://catchup.example/ch?start={timestamp}&duration={duration}",
+    };
+    expect(buildCatchupUrl(source, START, END, NOW)).toBe(
+      `http://catchup.example/ch?start=${Math.floor(NOW.getTime() / 1000)}&duration=5400`,
+    );
+  });
+});
diff --git a/web-ui/src/lib/catchup-url.ts b/web-ui/src/lib/catchup-url.ts
new file mode 100644
index 00000000..3ee95809
--- /dev/null
+++ b/web-ui/src/lib/catchup-url.ts
@@ -0,0 +1,272 @@
+import type { Source } from "../types/player";
+
+/**
+ * Parse long date format like yyyyMMddHHmmss.
+ * Used for ${utc:yyyyMMddHHmmss}, ${(b)yyyyMMddHHmmss}, and similar $ placeholders.
+ */
+function parseLongDate(date: Date, format: string, useUTC = false): string {
+  const year = (useUTC ? date.getUTCFullYear() : date.getFullYear()).toString();
+  const month = (useUTC ? date.getUTCMonth() + 1 : date.getMonth() + 1).toString().padStart(2, "0");
+  const day = (useUTC ? date.getUTCDate() : date.getDate()).toString().padStart(2, "0");
+  const hours = (useUTC ? date.getUTCHours() : date.getHours()).toString().padStart(2, "0");
+  const minutes = (useUTC ? date.getUTCMinutes() : date.getMinutes()).toString().padStart(2, "0");
+  const seconds = (useUTC ? date.getUTCSeconds() : date.getSeconds()).toString().padStart(2, "0");
+
+  return format
+    .replace(/yyyy/g, year)
+    .replace(/MM/g, month)
+    .replace(/dd/g, day)
+    .replace(/HH/g, hours)
+    .replace(/mm/g, minutes)
+    .replace(/ss/g, seconds);
+}
+
+/**
+ * Parse short date format like YmdHMS.
+ * Used for {utc:YmdHMS} and similar placeholders without `$`.
+ */
+function parseShortDate(date: Date, format: string, useUTC = false): string {
+  const convertedFormat = format
+    .replace(/Y/g, "yyyy")
+    .replace(/m/g, "__month__")
+    .replace(/d/g, "dd")
+    .replace(/H/g, "HH")
+    .replace(/M/g, "mm")
+    .replace(/S/g, "ss")
+    .replace(/__month__/g, "MM");
+  return parseLongDate(date, convertedFormat, useUTC);
+}
+
+/**
+ * Build a single catchup URL for a time range.
+ *
+ * Supported formats:
+ *
+ * Format with ${} (uses long format for custom formatters):
+ *   ${utc} - Start time in ISO8601 format
+ *   ${utc:yyyyMMddHHmmss} - Start time in UTC with long format
+ *   ${utcend} - End time in ISO8601 format
+ *   ${utcend:yyyyMMddHHmmss} - End time in UTC with long format
+ *   ${start} - Same as ${utc}
+ *   ${start:yyyyMMddHHmmss} - Same as ${utc:yyyyMMddHHmmss}
+ *   ${end} - Same as ${utcend}
+ *   ${end:yyyyMMddHHmmss} - Same as ${utcend:yyyyMMddHHmmss}
+ *   ${lutc} - Current time in UTC ISO8601 format
+ *   ${lutc:yyyyMMddHHmmss} - Current time in UTC with long format
+ *   ${now} - Same as ${lutc}
+ *   ${now:yyyyMMddHHmmss} - Same as ${lutc:yyyyMMddHHmmss}
+ *   ${timestamp} - Current unix timestamp (seconds)
+ *   ${timestamp:yyyyMMddHHmmss} - Same as ${lutc:yyyyMMddHHmmss}
+ *   ${(b)yyyyMMddHHmmss} - Start time in local time with long format
+ *   ${(e)yyyyMMddHHmmss} - End time in local time with long format
+ *   ${(b)yyyyMMdd|UTC} - Start time in UTC with long format (|UTC suffix)
+ *   ${(e)yyyyMMdd|UTC} - End time in UTC with long format (|UTC suffix)
+ *   ${(b)timestamp} - Start time unix timestamp (seconds)
+ *   ${(e)timestamp} - End time unix timestamp (seconds)
+ *   ${yyyy} - 4-digit year (YYYY) of start time in local time
+ *   ${MM} - Month (01-12) of start time in local time
+ *   ${dd} - Day (01-31) of start time in local time
+ *   ${HH} - Hour (00-23) of start time in local time
+ *   ${mm} - Minute (00-59) of start time in local time
+ *   ${ss} - Second (00-59) of start time in local time
+ *
+ * Format with {} (uses short format for custom formatters):
+ *   {utc} - Start time in ISO8601 format (same as ${utc})
+ *   {utc:YmdHMS} - Start time in UTC with short format
+ *   {utcend} - End time in ISO8601 format (same as ${utcend})
+ *   {utcend:YmdHMS} - End time in UTC with short format
+ *   {start} - Same as {utc}
+ *   {start:YmdHMS} - Same as {utc:YmdHMS}
+ *   {end} - Same as {utcend}
+ *   {end:YmdHMS} - Same as {utcend:YmdHMS}
+ *   {lutc} - Current time in UTC ISO8601 format (same as ${lutc})
+ *   {lutc:YmdHMS} - Current time in UTC with short format
+ *   {now} - Same as {lutc}
+ *   {now:YmdHMS} - Same as {lutc:YmdHMS}
+ *   {timestamp} - Current unix timestamp (seconds) (same as ${timestamp})
+ *   {timestamp:YmdHMS} - Same as {lutc:YmdHMS}
+ *   {(b)YmdHMS} - Start time in local time with short format
+ *   {(e)YmdHMS} - End time in local time with short format
+ *   {(b)YmdHMS|UTC} - Start time in UTC with short format (|UTC suffix)
+ *   {(e)YmdHMS|UTC} - End time in UTC with short format (|UTC suffix)
+ *   {(b)timestamp} - Start time unix timestamp (seconds)
+ *   {(e)timestamp} - End time unix timestamp (seconds)
+ *   {Y} - 4-digit year (YYYY) of start time in local time
+ *   {m} - Month (01-12) of start time in local time
+ *   {d} - Day (01-31) of start time in local time
+ *   {H} - Hour (00-23) of start time in local time
+ *   {M} - Minute (00-59) of start time in local time
+ *   {S} - Second (00-59) of start time in local time
+ *
+ * Special:
+ *   {duration} or ${duration} - Duration in seconds (segmentEndTime - segmentStartTime)
+ */
+export function buildCatchupUrl(
+  source: Source,
+  segmentStartTime: Date,
+  segmentEndTime: Date,
+  now = new Date(),
+): string {
+  if (!source.catchupSource) {
+    throw new Error("Source does not have catchup source configured");
+  }
+
+  const catchupMode = source.catchup || "default";
+  let processedSource = source.catchupSource;
+
+  const durationSeconds = Math.floor((segmentEndTime.getTime() - segmentStartTime.getTime()) / 1000);
+  const currentTimestamp = Math.floor(now.getTime() / 1000);
+
+  // Handle ${(b)format} and ${(e)format} - local time with long format
+  // Supports |UTC suffix to force UTC output, e.g. ${(b)yyyyMMdd|UTC}
+  processedSource = processedSource.replace(/\$\{(\([be]\))([^}]+)\}/g, (_match, timeType, format) => {
+    const date = timeType === "(b)" ? segmentStartTime : segmentEndTime;
+    const useUTC = format.endsWith("|UTC");
+    const cleanFormat = useUTC ? format.slice(0, -4) : format;
+    if (cleanFormat === "timestamp") {
+      return Math.floor(date.getTime() / 1000).toString();
+    }
+    return parseLongDate(date, cleanFormat, useUTC);
+  });
+
+  // Handle ${(b)} and ${(e)} - local time ISO8601
+  processedSource = processedSource.replace(/\$\{(\([be]\))\}/g, (_match, timeType) => {
+    const date = timeType === "(b)" ? segmentStartTime : segmentEndTime;
+    return date.toISOString();
+  });
+
+  // Handle {(b)format} and {(e)format} - local time with short format
+  // Supports |UTC suffix to force UTC output, e.g. {(b)YmdHMS|UTC}
+  processedSource = processedSource.replace(/\{(\([be]\))([^}]+)\}/g, (_match, timeType, format) => {
+    const date = timeType === "(b)" ? segmentStartTime : segmentEndTime;
+    const useUTC = format.endsWith("|UTC");
+    const cleanFormat = useUTC ? format.slice(0, -4) : format;
+    if (cleanFormat === "timestamp") {
+      return Math.floor(date.getTime() / 1000).toString();
+    }
+    return parseShortDate(date, cleanFormat, useUTC);
+  });
+
+  // Handle {(b)} and {(e)} - local time ISO8601
+  processedSource = processedSource.replace(/\{(\([be]\))\}/g, (_match, timeType) => {
+    const date = timeType === "(b)" ? segmentStartTime : segmentEndTime;
+    return date.toISOString();
+  });
+
+  // Handle ${keyword:format} - long format ($ variant)
+  processedSource = processedSource.replace(
+    /\$\{(utc|utcend|start|end|lutc|now|timestamp):([^}]+)\}/g,
+    (_match, keyword, format) => {
+      let date: Date;
+      switch (keyword) {
+        case "utc":
+        case "start":
+          date = segmentStartTime;
+          break;
+        case "utcend":
+        case "end":
+          date = segmentEndTime;
+          break;
+        case "lutc":
+        case "now":
+        case "timestamp":
+          date = now;
+          break;
+        default:
+          return "";
+      }
+      return parseLongDate(date, format, true);
+    },
+  );
+
+  // Handle ${keyword} - ISO8601 or timestamp ($ variant)
+  processedSource = processedSource.replace(/\$\{(utc|utcend|start|end|lutc|now|timestamp)\}/g, (_match, keyword) => {
+    switch (keyword) {
+      case "utc":
+      case "start":
+        return segmentStartTime.toISOString();
+      case "utcend":
+      case "end":
+        return segmentEndTime.toISOString();
+      case "lutc":
+      case "now":
+        return now.toISOString();
+      case "timestamp":
+        return currentTimestamp.toString();
+      default:
+        return "";
+    }
+  });
+
+  // Handle {keyword:format} - short format (no $ variant)
+  processedSource = processedSource.replace(
+    /\{(utc|utcend|start|end|lutc|now|timestamp):([^}]+)\}/g,
+    (_match, keyword, format) => {
+      let date: Date;
+      switch (keyword) {
+        case "utc":
+        case "start":
+          date = segmentStartTime;
+          break;
+        case "utcend":
+        case "end":
+          date = segmentEndTime;
+          break;
+        case "lutc":
+        case "now":
+        case "timestamp":
+          date = now;
+          break;
+        default:
+          return "";
+      }
+      return parseShortDate(date, format, true);
+    },
+  );
+
+  // Handle {keyword} - ISO8601 or timestamp (no $ variant)
+  processedSource = processedSource.replace(/\{(utc|utcend|start|end|lutc|now|timestamp)\}/g, (_match, keyword) => {
+    switch (keyword) {
+      case "utc":
+      case "start":
+        return segmentStartTime.toISOString();
+      case "utcend":
+      case "end":
+        return segmentEndTime.toISOString();
+      case "lutc":
+      case "now":
+        return now.toISOString();
+      case "timestamp":
+        return currentTimestamp.toString();
+      default:
+        return "";
+    }
+  });
+
+  // Handle individual component placeholders ${yyyy}, ${MM}, ${dd}, ${HH}, ${mm}, ${ss}
+  processedSource = processedSource.replace(/\$\{yyyy\}/g, segmentStartTime.getUTCFullYear().toString());
+  processedSource = processedSource.replace(
+    /\$\{MM\}/g,
+    (segmentStartTime.getUTCMonth() + 1).toString().padStart(2, "0"),
+  );
+  processedSource = processedSource.replace(/\$\{dd\}/g, segmentStartTime.getUTCDate().toString().padStart(2, "0"));
+  processedSource = processedSource.replace(/\$\{HH\}/g, segmentStartTime.getUTCHours().toString().padStart(2, "0"));
+  processedSource = processedSource.replace(/\$\{mm\}/g, segmentStartTime.getUTCMinutes().toString().padStart(2, "0"));
+  processedSource = processedSource.replace(/\$\{ss\}/g, segmentStartTime.getUTCSeconds().toString().padStart(2, "0"));
+
+  // Handle individual component placeholders {Y}, {m}, {d}, {H}, {M}, {S}
+  processedSource = processedSource.replace(/\{Y\}/g, segmentStartTime.getUTCFullYear().toString());
+  processedSource = processedSource.replace(/\{m\}/g, (segmentStartTime.getUTCMonth() + 1).toString().padStart(2, "0"));
+  processedSource = processedSource.replace(/\{d\}/g, segmentStartTime.getUTCDate().toString().padStart(2, "0"));
+  processedSource = processedSource.replace(/\{H\}/g, segmentStartTime.getUTCHours().toString().padStart(2, "0"));
+  processedSource = processedSource.replace(/\{M\}/g, segmentStartTime.getUTCMinutes().toString().padStart(2, "0"));
+  processedSource = processedSource.replace(/\{S\}/g, segmentStartTime.getUTCSeconds().toString().padStart(2, "0"));
+
+  // Handle {duration} and ${duration} - Duration in seconds
+  processedSource = processedSource.replace(/\$?\{duration\}/g, durationSeconds.toString());
+
+  if (catchupMode === "append") {
+    return source.url + processedSource;
+  }
+  return processedSource;
+}
diff --git a/web-ui/src/lib/clipboard.ts b/web-ui/src/lib/clipboard.ts
new file mode 100644
index 00000000..db5fc241
--- /dev/null
+++ b/web-ui/src/lib/clipboard.ts
@@ -0,0 +1,30 @@
+/**
+ * Copy text to the clipboard.
+ *
+ * `navigator.clipboard` is only available in a secure context (HTTPS or localhost).
+ * rtp2httpd is commonly opened over LAN HTTP, so fall back to execCommand.
+ */
+export async function copyTextToClipboard(text: string): Promise<void> {
+  if (typeof navigator !== "undefined" && window.isSecureContext && navigator.clipboard?.writeText) {
+    await navigator.clipboard.writeText(text);
+    return;
+  }
+  copyTextWithExecCommand(text);
+}
+
+function copyTextWithExecCommand(text: string): void {
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.setAttribute("readonly", "");
+  textarea.style.position = "fixed";
+  textarea.style.top = "0";
+  textarea.style.left = "-9999px";
+  document.body.appendChild(textarea);
+  textarea.select();
+  textarea.setSelectionRange(0, textarea.value.length);
+  const ok = document.execCommand("copy");
+  textarea.remove();
+  if (!ok) {
+    throw new Error("Failed to copy text");
+  }
+}
diff --git a/web-ui/src/lib/m3u-parser.test.ts b/web-ui/src/lib/m3u-parser.test.ts
new file mode 100644
index 00000000..238c931c
--- /dev/null
+++ b/web-ui/src/lib/m3u-parser.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import type { Source } from "../types/player";
+import { buildCatchupUrl } from "./catchup-url";
+import { planCatchupSegmentWindows } from "./catchup-windows";
+import { buildCatchupSegments } from "./m3u-parser";
+
+const NOW = new Date("2026-09-02T12:00:00.000Z");
+const HOURS = 60 * 60 * 1000;
+
+const source: Source = {
+  url: "http://live.example/ch",
+  catchup: "default",
+  catchupSource: "http://catchup.example/ch?playseek=${utc:yyyyMMddHHmmss}-${utcend:yyyyMMddHHmmss}",
+};
+
+describe("buildCatchupSegments", () => {
+  it("fills each planned window with the shared buildCatchupUrl helper", () => {
+    const start = new Date(NOW.getTime() - 2 * HOURS);
+    const programs = [
+      { start: new Date(NOW.getTime() - 3 * HOURS), end: new Date(NOW.getTime() - 90 * 60 * 1000) },
+      { start: new Date(NOW.getTime() - 90 * 60 * 1000), end: new Date(NOW.getTime() - 30 * 60 * 1000) },
+      { start: new Date(NOW.getTime() - 30 * 60 * 1000), end: new Date(NOW.getTime() + 30 * 60 * 1000) },
+    ];
+
+    const segments = buildCatchupSegments(source, start, { now: NOW, overlapMs: 0, programs });
+    const windows = planCatchupSegmentWindows(start, NOW, programs);
+
+    expect(segments.map((segment) => segment.url)).toEqual(
+      windows.map((window) => buildCatchupUrl(source, window.start, window.end, NOW)),
+    );
+  });
+});
diff --git a/web-ui/src/lib/m3u-parser.ts b/web-ui/src/lib/m3u-parser.ts
index 5402b496..35516ae1 100644
--- a/web-ui/src/lib/m3u-parser.ts
+++ b/web-ui/src/lib/m3u-parser.ts
@@ -1,9 +1,11 @@
 import type { PlayerSegment } from "../playback-engine";
 import type { Channel, M3UMetadata, Source } from "../types/player";
+import { buildCatchupUrl } from "./catchup-url";
 import { type CatchupProgramBound, clampCatchupStartTime, planCatchupSegmentWindows } from "./catchup-windows";
 import { toPlaylistRelativePath } from "./url";
 
 export { CATCHUP_MIN_DURATION_MS, clampCatchupStartTime } from "./catchup-windows";
+export { buildCatchupUrl } from "./catchup-url";
 
 /**
  * Parse M3U playlist content
@@ -205,296 +207,17 @@ export function buildCatchupSegments(
     throw new Error("Source does not have catchup source configured");
   }
 
-  const catchupMode = source.catchup || "default";
   const now = options.now ?? new Date();
   const startTime = clampCatchupStartTime(startTimeArg, now);
   const segments: PlayerSegment[] = [];
   const overlapMs = Math.max(0, options.overlapMs ?? CATCHUP_SEGMENT_OVERLAP_MS);
 
-  /**
-   * Parse long date format like yyyyMMddHHmmss
-   * Used for ${utc:yyyyMMddHHmmss}, ${utcend:yyyyMMddHHmmss} formats (with $)
-   * Also used for ${(b)yyyyMMddHHmmss} and ${(e)yyyyMMddHHmmss} formats
-   */
-  const parseLongDate = (date: Date, format: string, useUTC: boolean = false): string => {
-    const year = (useUTC ? date.getUTCFullYear() : date.getFullYear()).toString();
-    const month = (useUTC ? date.getUTCMonth() + 1 : date.getMonth() + 1).toString().padStart(2, "0");
-    const day = (useUTC ? date.getUTCDate() : date.getDate()).toString().padStart(2, "0");
-    const hours = (useUTC ? date.getUTCHours() : date.getHours()).toString().padStart(2, "0");
-    const minutes = (useUTC ? date.getUTCMinutes() : date.getMinutes()).toString().padStart(2, "0");
-    const seconds = (useUTC ? date.getUTCSeconds() : date.getSeconds()).toString().padStart(2, "0");
-
-    return format
-      .replace(/yyyy/g, year)
-      .replace(/MM/g, month)
-      .replace(/dd/g, day)
-      .replace(/HH/g, hours)
-      .replace(/mm/g, minutes)
-      .replace(/ss/g, seconds);
-  };
-
-  /**
-   * Parse short date format like YmdHMS
-   * Used for {utc:YmdHMS}, {utcend:YmdHMS} formats (without $)
-   * Converts Y/m/d/H/M/S to yyyy/MM/dd/HH/mm/ss and then calls parseLongDate
-   */
-  const parseShortDate = (date: Date, format: string, useUTC: boolean = false): string => {
-    // Use __month__ to avoid conflicts during replacement
-    const convertedFormat = format
-      .replace(/Y/g, "yyyy")
-      .replace(/m/g, "__month__")
-      .replace(/d/g, "dd")
-      .replace(/H/g, "HH")
-      .replace(/M/g, "mm")
-      .replace(/S/g, "ss")
-      .replace(/__month__/g, "MM");
-    return parseLongDate(date, convertedFormat, useUTC);
-  };
-
-  /**
-   * Build a single catchup URL for a time range
-   *
-   * Supported formats:
-   *
-   * Format with ${} (uses long format for custom formatters):
-   *   ${utc} - Start time in ISO8601 format
-   *   ${utc:yyyyMMddHHmmss} - Start time in UTC with long format
-   *   ${utcend} - End time in ISO8601 format
-   *   ${utcend:yyyyMMddHHmmss} - End time in UTC with long format
-   *   ${start} - Same as ${utc}
-   *   ${start:yyyyMMddHHmmss} - Same as ${utc:yyyyMMddHHmmss}
-   *   ${end} - Same as ${utcend}
-   *   ${end:yyyyMMddHHmmss} - Same as ${utcend:yyyyMMddHHmmss}
-   *   ${lutc} - Current time in UTC ISO8601 format
-   *   ${lutc:yyyyMMddHHmmss} - Current time in UTC with long format
-   *   ${now} - Same as ${lutc}
-   *   ${now:yyyyMMddHHmmss} - Same as ${lutc:yyyyMMddHHmmss}
-   *   ${timestamp} - Current unix timestamp (seconds)
-   *   ${timestamp:yyyyMMddHHmmss} - Same as ${lutc:yyyyMMddHHmmss}
-   *   ${(b)yyyyMMddHHmmss} - Start time in local time with long format
-   *   ${(e)yyyyMMddHHmmss} - End time in local time with long format
-   *   ${(b)yyyyMMdd|UTC} - Start time in UTC with long format (|UTC suffix)
-   *   ${(e)yyyyMMdd|UTC} - End time in UTC with long format (|UTC suffix)
-   *   ${(b)timestamp} - Start time unix timestamp (seconds)
-   *   ${(e)timestamp} - End time unix timestamp (seconds)
-   *   ${yyyy} - 4-digit year (YYYY) of start time in local time
-   *   ${MM} - Month (01-12) of start time in local time
-   *   ${dd} - Day (01-31) of start time in local time
-   *   ${HH} - Hour (00-23) of start time in local time
-   *   ${mm} - Minute (00-59) of start time in local time
-   *   ${ss} - Second (00-59) of start time in local time
-   *
-   * Format with {} (uses short format for custom formatters):
-   *   {utc} - Start time in ISO8601 format (same as ${utc})
-   *   {utc:YmdHMS} - Start time in UTC with short format
-   *   {utcend} - End time in ISO8601 format (same as ${utcend})
-   *   {utcend:YmdHMS} - End time in UTC with short format
-   *   {start} - Same as {utc}
-   *   {start:YmdHMS} - Same as {utc:YmdHMS}
-   *   {end} - Same as {utcend}
-   *   {end:YmdHMS} - Same as {utcend:YmdHMS}
-   *   {lutc} - Current time in UTC ISO8601 format (same as ${lutc})
-   *   {lutc:YmdHMS} - Current time in UTC with short format
-   *   {now} - Same as {lutc}
-   *   {now:YmdHMS} - Same as {lutc:YmdHMS}
-   *   {timestamp} - Current unix timestamp (seconds) (same as ${timestamp})
-   *   {timestamp:YmdHMS} - Same as {lutc:YmdHMS}
-   *   {(b)YmdHMS} - Start time in local time with short format
-   *   {(e)YmdHMS} - End time in local time with short format
-   *   {(b)YmdHMS|UTC} - Start time in UTC with short format (|UTC suffix)
-   *   {(e)YmdHMS|UTC} - End time in UTC with short format (|UTC suffix)
-   *   {(b)timestamp} - Start time unix timestamp (seconds)
-   *   {(e)timestamp} - End time unix timestamp (seconds)
-   *   {Y} - 4-digit year (YYYY) of start time in local time
-   *   {m} - Month (01-12) of start time in local time
-   *   {d} - Day (01-31) of start time in local time
-   *   {H} - Hour (00-23) of start time in local time
-   *   {M} - Minute (00-59) of start time in local time
-   *   {S} - Second (00-59) of start time in local time
-   *
-   * Special:
-   *   {duration} or ${duration} - Duration in seconds (segmentEndTime - segmentStartTime)
-   */
-  const buildCatchupUrl = (segmentStartTime: Date, segmentEndTime: Date): string => {
-    // Replace placeholders in catchup source
-    let processedSource = source.catchupSource ?? "";
-
-    const durationSeconds = Math.floor((segmentEndTime.getTime() - segmentStartTime.getTime()) / 1000);
-    const currentTimestamp = Math.floor(now.getTime() / 1000);
-
-    // Handle ${(b)format} and ${(e)format} - local time with long format
-    // Supports |UTC suffix to force UTC output, e.g. ${(b)yyyyMMdd|UTC}
-    processedSource = processedSource.replace(/\$\{(\([be]\))([^}]+)\}/g, (_match, timeType, format) => {
-      const date = timeType === "(b)" ? segmentStartTime : segmentEndTime;
-      const useUTC = format.endsWith("|UTC");
-      const cleanFormat = useUTC ? format.slice(0, -4) : format;
-      if (cleanFormat === "timestamp") {
-        return Math.floor(date.getTime() / 1000).toString();
-      }
-      return parseLongDate(date, cleanFormat, useUTC);
-    });
-
-    // Handle ${(b)} and ${(e)} - local time ISO8601
-    processedSource = processedSource.replace(/\$\{(\([be]\))\}/g, (_match, timeType) => {
-      const date = timeType === "(b)" ? segmentStartTime : segmentEndTime;
-      return date.toISOString();
-    });
-
-    // Handle {(b)format} and {(e)format} - local time with short format
-    // Supports |UTC suffix to force UTC output, e.g. {(b)YmdHMS|UTC}
-    processedSource = processedSource.replace(/\{(\([be]\))([^}]+)\}/g, (_match, timeType, format) => {
-      const date = timeType === "(b)" ? segmentStartTime : segmentEndTime;
-      const useUTC = format.endsWith("|UTC");
-      const cleanFormat = useUTC ? format.slice(0, -4) : format;
-      if (cleanFormat === "timestamp") {
-        return Math.floor(date.getTime() / 1000).toString();
-      }
-      return parseShortDate(date, cleanFormat, useUTC);
-    });
-
-    // Handle {(b)} and {(e)} - local time ISO8601
-    processedSource = processedSource.replace(/\{(\([be]\))\}/g, (_match, timeType) => {
-      const date = timeType === "(b)" ? segmentStartTime : segmentEndTime;
-      return date.toISOString();
-    });
-
-    // Handle ${keyword:format} - long format ($ variant)
-    processedSource = processedSource.replace(
-      /\$\{(utc|utcend|start|end|lutc|now|timestamp):([^}]+)\}/g,
-      (_match, keyword, format) => {
-        let date: Date;
-        switch (keyword) {
-          case "utc":
-          case "start":
-            date = segmentStartTime;
-            break;
-          case "utcend":
-          case "end":
-            date = segmentEndTime;
-            break;
-          case "lutc":
-          case "now":
-          case "timestamp":
-            date = now;
-            break;
-          default:
-            return "";
-        }
-        return parseLongDate(date, format, true);
-      },
-    );
-
-    // Handle ${keyword} - ISO8601 or timestamp ($ variant)
-    processedSource = processedSource.replace(/\$\{(utc|utcend|start|end|lutc|now|timestamp)\}/g, (_match, keyword) => {
-      switch (keyword) {
-        case "utc":
-        case "start":
-          return segmentStartTime.toISOString();
-        case "utcend":
-        case "end":
-          return segmentEndTime.toISOString();
-        case "lutc":
-        case "now":
-          return now.toISOString();
-        case "timestamp":
-          return currentTimestamp.toString();
-        default:
-          return "";
-      }
-    });
-
-    // Handle {keyword:format} - short format (no $ variant)
-    processedSource = processedSource.replace(
-      /\{(utc|utcend|start|end|lutc|now|timestamp):([^}]+)\}/g,
-      (_match, keyword, format) => {
-        let date: Date;
-        switch (keyword) {
-          case "utc":
-          case "start":
-            date = segmentStartTime;
-            break;
-          case "utcend":
-          case "end":
-            date = segmentEndTime;
-            break;
-          case "lutc":
-          case "now":
-          case "timestamp":
-            date = now;
-            break;
-          default:
-            return "";
-        }
-        return parseShortDate(date, format, true);
-      },
-    );
-
-    // Handle {keyword} - ISO8601 or timestamp (no $ variant)
-    processedSource = processedSource.replace(/\{(utc|utcend|start|end|lutc|now|timestamp)\}/g, (_match, keyword) => {
-      switch (keyword) {
-        case "utc":
-        case "start":
-          return segmentStartTime.toISOString();
-        case "utcend":
-        case "end":
-          return segmentEndTime.toISOString();
-        case "lutc":
-        case "now":
-          return now.toISOString();
-        case "timestamp":
-          return currentTimestamp.toString();
-        default:
-          return "";
-      }
-    });
-
-    // Handle individual component placeholders ${yyyy}, ${MM}, ${dd}, ${HH}, ${mm}, ${ss}
-    processedSource = processedSource.replace(/\$\{yyyy\}/g, segmentStartTime.getUTCFullYear().toString());
-    processedSource = processedSource.replace(
-      /\$\{MM\}/g,
-      (segmentStartTime.getUTCMonth() + 1).toString().padStart(2, "0"),
-    );
-    processedSource = processedSource.replace(/\$\{dd\}/g, segmentStartTime.getUTCDate().toString().padStart(2, "0"));
-    processedSource = processedSource.replace(/\$\{HH\}/g, segmentStartTime.getUTCHours().toString().padStart(2, "0"));
-    processedSource = processedSource.replace(
-      /\$\{mm\}/g,
-      segmentStartTime.getUTCMinutes().toString().padStart(2, "0"),
-    );
-    processedSource = processedSource.replace(
-      /\$\{ss\}/g,
-      segmentStartTime.getUTCSeconds().toString().padStart(2, "0"),
-    );
-
-    // Handle individual component placeholders {Y}, {m}, {d}, {H}, {M}, {S}
-    processedSource = processedSource.replace(/\{Y\}/g, segmentStartTime.getUTCFullYear().toString());
-    processedSource = processedSource.replace(
-      /\{m\}/g,
-      (segmentStartTime.getUTCMonth() + 1).toString().padStart(2, "0"),
-    );
-    processedSource = processedSource.replace(/\{d\}/g, segmentStartTime.getUTCDate().toString().padStart(2, "0"));
-    processedSource = processedSource.replace(/\{H\}/g, segmentStartTime.getUTCHours().toString().padStart(2, "0"));
-    processedSource = processedSource.replace(/\{M\}/g, segmentStartTime.getUTCMinutes().toString().padStart(2, "0"));
-    processedSource = processedSource.replace(/\{S\}/g, segmentStartTime.getUTCSeconds().toString().padStart(2, "0"));
-
-    // Handle {duration} and ${duration} - Duration in seconds
-    processedSource = processedSource.replace(/\$?\{duration\}/g, durationSeconds.toString());
-
-    // Build final URL based on catchup mode
-    if (catchupMode === "append") {
-      // Append mode: append catchup source to original channel URL
-      return source.url + processedSource;
-    } else {
-      // Default mode: use catchup source as complete URL
-      return processedSource;
-    }
-  };
-
   const buildOverlappedSegmentUrl = (segmentStartTime: Date, segmentEndTime: Date): string => {
     const requestStartTime =
       segments.length === 0
         ? segmentStartTime
         : new Date(Math.max(startTime.getTime(), segmentStartTime.getTime() - overlapMs));
-    return buildCatchupUrl(requestStartTime, segmentEndTime);
+    return buildCatchupUrl(source, requestStartTime, segmentEndTime, now);
   };
 
   for (const timeWindow of planCatchupSegmentWindows(startTimeArg, now, options.programs)) {
diff --git a/web-ui/src/lib/media-direct-link.test.ts b/web-ui/src/lib/media-direct-link.test.ts
new file mode 100644
index 00000000..e7dba0c1
--- /dev/null
+++ b/web-ui/src/lib/media-direct-link.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import type { Channel } from "../types/player";
+import { buildCatchupUrl } from "./catchup-url";
+import { CATCHUP_MIN_DURATION_MS } from "./catchup-windows";
+import {
+  getChannelLiveMediaUrl,
+  getProgramMediaUrl,
+  stripPlaylistUrlLabel,
+  toAbsoluteMediaUrl,
+} from "./media-direct-link";
+
+const NOW = new Date("2026-09-02T12:00:00.000Z");
+
+function channel(overrides: Partial<Channel> = {}): Channel {
+  return {
+    id: "1",
+    name: "Catchup Channel",
+    groups: ["Test"],
+    sources: [
+      {
+        url: "/Test/Catchup Channel",
+        catchup: "default",
+        catchupSource: "/Test/Catchup Channel/catchup?playseek=${(b)yyyyMMddHHmmss|UTC}-${(e)yyyyMMddHHmmss|UTC}",
+      },
+    ],
+    ...overrides,
+  };
+}
+
+describe("stripPlaylistUrlLabel", () => {
+  it("strips a trailing $label and leaves ${placeholders} intact", () => {
+    expect(stripPlaylistUrlLabel("http://example/ch$HD")).toBe("http://example/ch");
+    expect(stripPlaylistUrlLabel("http://example/ch?t=${utc}$HD")).toBe("http://example/ch?t=${utc}");
+  });
+});
+
+describe("toAbsoluteMediaUrl", () => {
+  it("resolves relative URLs against the given base and strips labels", () => {
+    expect(toAbsoluteMediaUrl("/Test/Live Only$HD", "http://127.0.0.1:8080/")).toBe(
+      "http://127.0.0.1:8080/Test/Live%20Only",
+    );
+  });
+});
+
+describe("getChannelLiveMediaUrl", () => {
+  it("returns the live source URL", () => {
+    expect(getChannelLiveMediaUrl(channel(), 0)).toBe("/Test/Catchup Channel");
+  });
+});
+
+describe("getProgramMediaUrl", () => {
+  it("copies a single programme window via buildCatchupUrl, not a multi-segment plan", () => {
+    const start = new Date("2026-09-02T10:00:00.000Z");
+    const end = new Date("2026-09-02T12:00:00.000Z");
+    const ch = channel();
+    const url = getProgramMediaUrl(ch, { start, end }, 0, NOW);
+
+    expect(url).toBe(buildCatchupUrl(ch.sources[0], start, end, NOW));
+    expect(url).toBe("/Test/Catchup Channel/catchup?playseek=20260902100000-20260902120000");
+  });
+
+  it("pads programmes shorter than CATCHUP_MIN_DURATION_MS", () => {
+    const start = new Date("2026-09-02T10:00:00.000Z");
+    const end = new Date(start.getTime() + 5_000);
+    const ch = channel();
+    const paddedEnd = new Date(start.getTime() + CATCHUP_MIN_DURATION_MS);
+
+    expect(getProgramMediaUrl(ch, { start, end }, 0, NOW)).toBe(buildCatchupUrl(ch.sources[0], start, paddedEnd, NOW));
+  });
+
+  it("falls back to the live URL for an on-air programme without catchup", () => {
+    const liveOnly = channel({
+      sources: [{ url: "/Test/Live Only" }],
+    });
+    const url = getProgramMediaUrl(
+      liveOnly,
+      { start: new Date("2026-09-02T11:00:00.000Z"), end: new Date("2026-09-02T13:00:00.000Z") },
+      0,
+      NOW,
+    );
+    expect(url).toBe("/Test/Live Only");
+  });
+
+  it("returns null for a past programme without catchup", () => {
+    const liveOnly = channel({
+      sources: [{ url: "/Test/Live Only" }],
+    });
+    expect(
+      getProgramMediaUrl(
+        liveOnly,
+        { start: new Date("2026-09-02T09:00:00.000Z"), end: new Date("2026-09-02T10:00:00.000Z") },
+        0,
+        NOW,
+      ),
+    ).toBeNull();
+  });
+});
diff --git a/web-ui/src/lib/media-direct-link.ts b/web-ui/src/lib/media-direct-link.ts
new file mode 100644
index 00000000..58b8a7b1
--- /dev/null
+++ b/web-ui/src/lib/media-direct-link.ts
@@ -0,0 +1,102 @@
+import type { Channel, Source } from "../types/player";
+import { buildCatchupUrl } from "./catchup-url";
+import { CATCHUP_MIN_DURATION_MS, type CatchupProgramBound } from "./catchup-windows";
+import { getLastSourceIndex } from "./player-storage";
+
+/**
+ * Strip a trailing `$label` suffix the same way the server does.
+ * `${...}` placeholders are left intact.
+ */
+export function stripPlaylistUrlLabel(url: string): string {
+  for (let i = url.length - 1; i >= 0; i--) {
+    if (url[i] !== "$") continue;
+    if (i === url.length - 1) continue;
+    if (url[i + 1] === "{") continue;
+    return url.slice(0, i);
+  }
+  return url;
+}
+
+function readPageR2hToken(): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const fromQuery = new URL(window.location.href).searchParams.get("r2h-token");
+    if (fromQuery) return fromQuery;
+  } catch {
+    // Ignore malformed locations and fall through to the cookie.
+  }
+  const match = document.cookie.match(/(?:^|;\s*)r2h-token=([^;]*)/);
+  if (!match?.[1]) return null;
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+function withPageAuthToken(url: string): string {
+  const token = readPageR2hToken();
+  if (!token) return url;
+  try {
+    const parsed = new URL(url);
+    if (!parsed.searchParams.has("r2h-token")) {
+      parsed.searchParams.set("r2h-token", token);
+    }
+    return parsed.href;
+  } catch {
+    return url;
+  }
+}
+
+export function toAbsoluteMediaUrl(
+  url: string,
+  baseHref = typeof document === "undefined" ? undefined : document.baseURI,
+): string {
+  const stripped = stripPlaylistUrlLabel(url);
+  let absolute = stripped;
+  try {
+    absolute = baseHref ? new URL(stripped, baseHref).href : stripped;
+  } catch {
+    absolute = stripped;
+  }
+  return withPageAuthToken(absolute);
+}
+
+export function pickChannelSource(channel: Channel, preferredIndex?: number): Source | undefined {
+  const index = preferredIndex ?? getLastSourceIndex(channel.id);
+  return channel.sources[index] ?? channel.sources[0];
+}
+
+export function pickCatchupSource(channel: Channel, preferredIndex?: number): Source | undefined {
+  const preferred = pickChannelSource(channel, preferredIndex);
+  if (preferred?.catchup && preferred.catchupSource) return preferred;
+  return channel.sources.find((source) => Boolean(source.catchup && source.catchupSource));
+}
+
+export function getChannelLiveMediaUrl(channel: Channel, preferredIndex?: number): string | null {
+  const source = pickChannelSource(channel, preferredIndex);
+  if (!source?.url) return null;
+  return toAbsoluteMediaUrl(source.url);
+}
+
+export function getProgramMediaUrl(
+  channel: Channel,
+  program: CatchupProgramBound,
+  preferredIndex?: number,
+  now = new Date(),
+): string | null {
+  const catchupSource = pickCatchupSource(channel, preferredIndex);
+  if (catchupSource) {
+    const start = program.start;
+    const end = new Date(Math.max(program.end.getTime(), start.getTime() + CATCHUP_MIN_DURATION_MS));
+    return toAbsoluteMediaUrl(buildCatchupUrl(catchupSource, start, end, now));
+  }
+  if (program.start.getTime() <= now.getTime() && program.end.getTime() > now.getTime()) {
+    return getChannelLiveMediaUrl(channel, preferredIndex);
+  }
+  return null;
+}
+
+export function isMiddleMouseButton(event: { button: number }): boolean {
+  return event.button === 1;
+}
diff --git a/web-ui/src/pages/player.tsx b/web-ui/src/pages/player.tsx
index 12028d67..808eb4b8 100644
--- a/web-ui/src/pages/player.tsx
+++ b/web-ui/src/pages/player.tsx
@@ -8,6 +8,7 @@ import {
 } from "../components/player/channel-list";
 import { EPGView, nextScrollBehaviorRef as epgViewNextScrollBehaviorRef } from "../components/player/epg-view";
 import { createPlaybackClock } from "../components/player/playback-clock";
+import { PlayerToast, usePlayerToast } from "../components/player/player-toast";
 import { SettingsDropdown } from "../components/player/settings-dropdown";
 import { VideoPlayer } from "../components/player/video-player";
 import { Button, buttonVariants } from "../components/ui/button";
@@ -18,11 +19,13 @@ import { usePersistedEnum } from "../hooks/use-persisted-enum";
 import { usePlayerAppearance } from "../hooks/use-player-appearance";
 import { usePlayerTranslation } from "../hooks/use-player-translation";
 import { useTheme } from "../hooks/use-theme";
+import { copyTextToClipboard } from "../lib/clipboard";
 import { isDocumentPictureInPictureSupported } from "../lib/document-picture-in-picture";
 import { loadEPG } from "../lib/epg-loader";
 import { type EPGChannelDescriptor, type EPGData, getAllChannelPrograms, getEPGChannelId } from "../lib/epg-parser";
 import type { Locale } from "../lib/locale";
 import { buildCatchupSegments, clampCatchupStartTime, parseM3U } from "../lib/m3u-parser";
+import { getChannelLiveMediaUrl, getProgramMediaUrl } from "../lib/media-direct-link";
 import { isLGWebOS } from "../lib/platform";
 import { findDeepLinkChannel, syncChannelDeepLink } from "../lib/player-deep-link";
 import {
@@ -42,7 +45,7 @@ import {
 import { buildAppPath } from "../lib/url";
 import { getPlaybackBackendKind, type PlayerSegment } from "../playback-engine";
 import { mseToWallClock, NEAR_LIVE_EDGE_MS } from "../playback-engine/timeline/wall-clock";
-import type { Channel, M3UMetadata } from "../types/player";
+import type { Channel, EPGProgram, M3UMetadata } from "../types/player";
 import { PICTURE_IN_PICTURE_MODES, type PictureInPictureMode } from "../types/ui";
 
 function getM3UIntegrationGuideUrl(locale: Locale) {
@@ -99,6 +102,7 @@ function PlayerPage() {
     PICTURE_IN_PICTURE_MODES,
   );
   const t = usePlayerTranslation(locale);
+  const { toast, showToast } = usePlayerToast();
 
   const [metadata, setMetadata] = useState<M3UMetadata | null>(null);
   const [epgData, setEpgData] = useState<EPGData>({});
@@ -255,6 +259,41 @@ function PlayerPage() {
     [handleVideoSeek],
   );
 
+  const copyMediaLink = useCallback(
+    async (url: string | null) => {
+      if (!url) {
+        showToast(t("copyMediaLinkUnavailable"), "error");
+        return;
+      }
+      try {
+        await copyTextToClipboard(url);
+        showToast(t("mediaLinkCopied"));
+      } catch {
+        showToast(t("copyMediaLinkFailed"), "error");
+      }
+    },
+    [showToast, t],
+  );
+
+  const handleChannelCopyLink = useCallback(
+    (channel: Channel) => {
+      const preferredIndex = channel.id === currentChannel?.id ? activeSourceIndex : getLastSourceIndex(channel.id);
+      void copyMediaLink(getChannelLiveMediaUrl(channel, preferredIndex));
+    },
+    [activeSourceIndex, copyMediaLink, currentChannel],
+  );
+
+  const handleProgramCopyLink = useCallback(
+    (program: EPGProgram) => {
+      if (!currentChannel) {
+        void copyMediaLink(null);
+        return;
+      }
+      void copyMediaLink(getProgramMediaUrl(currentChannel, program, activeSourceIndex));
+    },
+    [activeSourceIndex, copyMediaLink, currentChannel],
+  );
+
   const handleSourceChange = useCallback(
     (sourceIndex: number) => {
       if (playMode === "live") {
@@ -646,6 +685,7 @@ function PlayerPage() {
                   groups={metadata?.groups}
                   currentChannel={currentChannel}
                   onChannelSelect={selectChannel}
+                  onCopyMediaLink={handleChannelCopyLink}
                   locale={locale}
                   settingsSlot={settingsSlot}
                   epgData={epgData}
@@ -656,6 +696,7 @@ function PlayerPage() {
                   channelId={currentEpgChannelId}
                   epgData={epgData}
                   onProgramSelect={handleProgramSelect}
+                  onCopyMediaLink={handleProgramCopyLink}
                   locale={locale}
                   supportsCatchup={!!currentChannel?.sources.some((s) => s.catchup && s.catchupSource)}
                   currentPlayingProgram={currentVideoProgram}
@@ -665,6 +706,8 @@ function PlayerPage() {
           </div>
         </div>
 
+        <PlayerToast toast={toast} />
+
         {/* Loading overlay shares the player viewport to avoid iOS standalone fixed-position gaps. */}
         {isLoading && (
           <div

From e93eae221080178714ad90790087edebc107c0a7 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 2 Sep 2026 09:44:53 +0000
Subject: [PATCH 2/8] style(web-player): satisfy biome on shared catchup URL
 tests

Co-authored-by: Stackie Jia <jsq2627@gmail.com>
---
 web-ui/src/lib/catchup-url.test.ts       | 4 ++--
 web-ui/src/lib/m3u-parser.test.ts        | 2 +-
 web-ui/src/lib/m3u-parser.ts             | 2 +-
 web-ui/src/lib/media-direct-link.test.ts | 7 ++++---
 4 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/web-ui/src/lib/catchup-url.test.ts b/web-ui/src/lib/catchup-url.test.ts
index aa627654..2262b535 100644
--- a/web-ui/src/lib/catchup-url.test.ts
+++ b/web-ui/src/lib/catchup-url.test.ts
@@ -9,7 +9,7 @@ const END = new Date("2026-09-02T11:30:00.000Z");
 const defaultSource: Source = {
   url: "http://live.example/ch",
   catchup: "default",
-  catchupSource: "http://catchup.example/ch?playseek=${utc:yyyyMMddHHmmss}-${utcend:yyyyMMddHHmmss}",
+  catchupSource: "http://catchup.example/ch?playseek={utc:YmdHMS}-{utcend:YmdHMS}",
 };
 
 describe("buildCatchupUrl", () => {
@@ -23,7 +23,7 @@ describe("buildCatchupUrl", () => {
     const source: Source = {
       url: "http://live.example/ch",
       catchup: "append",
-      catchupSource: "/catchup?playseek=${(b)yyyyMMddHHmmss|UTC}-${(e)yyyyMMddHHmmss|UTC}",
+      catchupSource: "/catchup?playseek={(b)YmdHMS|UTC}-{(e)YmdHMS|UTC}",
     };
     expect(buildCatchupUrl(source, START, END, NOW)).toBe(
       "http://live.example/ch/catchup?playseek=20260902100000-20260902113000",
diff --git a/web-ui/src/lib/m3u-parser.test.ts b/web-ui/src/lib/m3u-parser.test.ts
index 238c931c..0df7188f 100644
--- a/web-ui/src/lib/m3u-parser.test.ts
+++ b/web-ui/src/lib/m3u-parser.test.ts
@@ -10,7 +10,7 @@ const HOURS = 60 * 60 * 1000;
 const source: Source = {
   url: "http://live.example/ch",
   catchup: "default",
-  catchupSource: "http://catchup.example/ch?playseek=${utc:yyyyMMddHHmmss}-${utcend:yyyyMMddHHmmss}",
+  catchupSource: "http://catchup.example/ch?playseek={utc:YmdHMS}-{utcend:YmdHMS}",
 };
 
 describe("buildCatchupSegments", () => {
diff --git a/web-ui/src/lib/m3u-parser.ts b/web-ui/src/lib/m3u-parser.ts
index 35516ae1..c45a5952 100644
--- a/web-ui/src/lib/m3u-parser.ts
+++ b/web-ui/src/lib/m3u-parser.ts
@@ -4,8 +4,8 @@ import { buildCatchupUrl } from "./catchup-url";
 import { type CatchupProgramBound, clampCatchupStartTime, planCatchupSegmentWindows } from "./catchup-windows";
 import { toPlaylistRelativePath } from "./url";
 
-export { CATCHUP_MIN_DURATION_MS, clampCatchupStartTime } from "./catchup-windows";
 export { buildCatchupUrl } from "./catchup-url";
+export { CATCHUP_MIN_DURATION_MS, clampCatchupStartTime } from "./catchup-windows";
 
 /**
  * Parse M3U playlist content
diff --git a/web-ui/src/lib/media-direct-link.test.ts b/web-ui/src/lib/media-direct-link.test.ts
index e7dba0c1..20726814 100644
--- a/web-ui/src/lib/media-direct-link.test.ts
+++ b/web-ui/src/lib/media-direct-link.test.ts
@@ -20,7 +20,7 @@ function channel(overrides: Partial<Channel> = {}): Channel {
       {
         url: "/Test/Catchup Channel",
         catchup: "default",
-        catchupSource: "/Test/Catchup Channel/catchup?playseek=${(b)yyyyMMddHHmmss|UTC}-${(e)yyyyMMddHHmmss|UTC}",
+        catchupSource: "/Test/Catchup Channel/catchup?playseek={(b)YmdHMS|UTC}-{(e)YmdHMS|UTC}",
       },
     ],
     ...overrides,
@@ -28,9 +28,10 @@ function channel(overrides: Partial<Channel> = {}): Channel {
 }
 
 describe("stripPlaylistUrlLabel", () => {
-  it("strips a trailing $label and leaves ${placeholders} intact", () => {
+  it("strips a trailing $label and leaves catchup placeholders intact", () => {
+    const placeholderUrl = "http://example/ch?t=$" + "{utc}$HD";
     expect(stripPlaylistUrlLabel("http://example/ch$HD")).toBe("http://example/ch");
-    expect(stripPlaylistUrlLabel("http://example/ch?t=${utc}$HD")).toBe("http://example/ch?t=${utc}");
+    expect(stripPlaylistUrlLabel(placeholderUrl)).toBe("http://example/ch?t=$" + "{utc}");
   });
 });
 

From c87ff668eff67668f6b0f55fd1770ff16354b72b Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 2 Sep 2026 10:06:57 +0000
Subject: [PATCH 3/8] docs(web-player): move features above access

Drop the copy-media-link bullet from the features list; the dedicated section already covers it.

Co-authored-by: Stackie Jia <jsq2627@gmail.com>
---
 docs/en/guide/web-player.md | 29 ++++++++++++++---------------
 docs/guide/web-player.md    | 29 ++++++++++++++---------------
 2 files changed, 28 insertions(+), 30 deletions(-)

diff --git a/docs/en/guide/web-player.md b/docs/en/guide/web-player.md
index 71cf1ba0..913f34a4 100644
--- a/docs/en/guide/web-player.md
+++ b/docs/en/guide/web-player.md
@@ -2,6 +2,20 @@
 
 rtp2httpd includes a modern web-based player that allows you to watch configured M3U channel lists directly in your browser without installing any client software.
 
+## Features
+
+- **Channel List**: Automatically loads configured M3U channel lists
+- **Live Streaming**: Watch live broadcasts directly in the browser
+- **Time-Shifted Playback**: Supports EPG (Electronic Program Guide) and time-shifted playback (requires catchup source)
+- **Fast Startup**: Achieves millisecond-level channel switching with FCC
+- **Seamless Channel Switching**: Preloads the new stream when switching channels to reduce black screens
+- **Responsive Design**: UI adapts to both desktop and mobile devices
+- **PWA Support**: Can be added to the home screen on phones, tablets, desktops, or LG webOS TVs for app-like quick access
+- **Zero Overhead**: Pure web frontend implementation with virtually no resource overhead on rtp2httpd (no decoding/transcoding overhead)
+
+> [!IMPORTANT]
+> The player relies on the browser's native decoding capabilities. Some encoding formats (such as E-AC3) may not play in certain browsers (manifested as no audio or black screen). We recommend using the latest versions of Chrome, Edge, or Safari.
+
 ## Access
 
 After configuring M3U playlists, access the player via your browser:
@@ -38,21 +52,6 @@ The copied value is a directly requestable HTTP media URL, which you can downloa
 > [!NOTE]
 > An on-air program with no catch-up source copies the live URL. A program that has not started and has no catch-up source cannot be copied.
 
-## Features
-
-- **Channel List**: Automatically loads configured M3U channel lists
-- **Copy Media Links**: Middle-click a channel or program to copy its live or catch-up URL
-- **Live Streaming**: Watch live broadcasts directly in the browser
-- **Time-Shifted Playback**: Supports EPG (Electronic Program Guide) and time-shifted playback (requires catchup source)
-- **Fast Startup**: Achieves millisecond-level channel switching with FCC
-- **Seamless Channel Switching**: Preloads the new stream when switching channels to reduce black screens
-- **Responsive Design**: UI adapts to both desktop and mobile devices
-- **PWA Support**: Can be added to the home screen on phones, tablets, desktops, or LG webOS TVs for app-like quick access
-- **Zero Overhead**: Pure web frontend implementation with virtually no resource overhead on rtp2httpd (no decoding/transcoding overhead)
-
-> [!IMPORTANT]
-> The player relies on the browser's native decoding capabilities. Some encoding formats (such as E-AC3) may not play in certain browsers (manifested as no audio or black screen). We recommend using the latest versions of Chrome, Edge, or Safari.
-
 ## PWA Support and Add to Home Screen
 
 The built-in web player supports PWA (Progressive Web App). You can add the player page to your device's home screen (including phones, tablets, computers, and LG webOS smart TVs) and launch it like a native app for a full-screen, immersive viewing experience.
diff --git a/docs/guide/web-player.md b/docs/guide/web-player.md
index c2819607..2cf71cd9 100644
--- a/docs/guide/web-player.md
+++ b/docs/guide/web-player.md
@@ -2,6 +2,20 @@
 
 rtp2httpd 内置了一个基于 Web 的现代化播放器，可以直接在浏览器中观看已配置的 M3U 频道列表，无需安装任何客户端。
 
+## 功能特性
+
+- **频道列表**：自动加载配置的 M3U 频道列表
+- **在线直播**：在浏览器中直接观看直播
+- **时移回看**：支持 EPG 电子节目单和时移回看（需要有回看源）
+- **快速起播**：搭配 FCC 可实现毫秒级换台速度
+- **无缝换台**：换台时预加载新流，减少黑屏
+- **响应式设计**：桌面和移动端 UI 自适应
+- **PWA 支持**：可添加到手机、平板、桌面或 LG webOS 电视主屏幕，像原生应用一样快捷打开
+- **零开销**：纯 Web 前端实现，对 rtp2httpd 运行几乎没有资源占用（无解码转码开销）
+
+> [!IMPORTANT]
+> 播放器依赖浏览器的原生解码能力，部分编码格式（如 E-AC3）可能在某些浏览器中无法播放（表现为无音频、画面黑屏）。推荐使用最新版本的 Chrome、Edge 或 Safari。
+
 ## 访问方式
 
 配置好 M3U 播放列表后，通过浏览器访问：
@@ -38,21 +52,6 @@ http://服务器地址:端口/player#CCTV-1
 > [!NOTE]
 > 正在播出且没有回看源的节目会复制直播地址。尚未开始且没有回看源的节目无法复制。
 
-## 功能特性
-
-- **频道列表**：自动加载配置的 M3U 频道列表
-- **复制媒体直链**：中键点击频道或节目，复制直播或回看地址
-- **在线直播**：在浏览器中直接观看直播
-- **时移回看**：支持 EPG 电子节目单和时移回看（需要有回看源）
-- **快速起播**：搭配 FCC 可实现毫秒级换台速度
-- **无缝换台**：换台时预加载新流，减少黑屏
-- **响应式设计**：桌面和移动端 UI 自适应
-- **PWA 支持**：可添加到手机、平板、桌面或 LG webOS 电视主屏幕，像原生应用一样快捷打开
-- **零开销**：纯 Web 前端实现，对 rtp2httpd 运行几乎没有资源占用（无解码转码开销）
-
-> [!IMPORTANT]
-> 播放器依赖浏览器的原生解码能力，部分编码格式（如 E-AC3）可能在某些浏览器中无法播放（表现为无音频、画面黑屏）。推荐使用最新版本的 Chrome、Edge 或 Safari。
-
 ## PWA 支持与添加到主屏幕
 
 内置 Web 播放器支持 PWA（Progressive Web App）。你可以将播放器页面添加到设备主屏幕（包括手机、平板、电脑，以及 LG webOS 智能电视），像打开原生应用一样一键进入，获得全屏、沉浸式的观看体验。

From e5a025034a3d0ab666e0fe7be9b0b90770e4fe84 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 2 Sep 2026 10:10:07 +0000
Subject: [PATCH 4/8] fix(web-player): drop copy-link hover tooltip

Middle-click copy is a hidden gesture; the button title delayed native tooltip on hover.

Co-authored-by: Stackie Jia <jsq2627@gmail.com>
---
 web-ui/src/components/player/channel-list-item.tsx | 1 -
 web-ui/src/components/player/epg-view.tsx          | 1 -
 web-ui/src/i18n/player.ts                          | 3 ---
 3 files changed, 5 deletions(-)

diff --git a/web-ui/src/components/player/channel-list-item.tsx b/web-ui/src/components/player/channel-list-item.tsx
index 01a5a7ca..425c1115 100644
--- a/web-ui/src/components/player/channel-list-item.tsx
+++ b/web-ui/src/components/player/channel-list-item.tsx
@@ -51,7 +51,6 @@ const ChannelListItemComponent = forwardRef<HTMLButtonElement, ChannelListItemPr
         type="button"
         key={channel.id}
         ref={ref}
-        title={t("copyMediaLinkHint")}
         className={clsx(
           PLAYER_LIST_SURFACE_BASE_CLASS,
           PLAYER_CHANNEL_LIST_ITEM_CLASS,
diff --git a/web-ui/src/components/player/epg-view.tsx b/web-ui/src/components/player/epg-view.tsx
index 7ddd0cb0..9f855bcc 100644
--- a/web-ui/src/components/player/epg-view.tsx
+++ b/web-ui/src/components/player/epg-view.tsx
@@ -102,7 +102,6 @@ const EPGProgramItem = memo(function EPGProgramItem({
     <button
       type="button"
       ref={playing ? currentProgramRef : null}
-      title={t("copyMediaLinkHint")}
       className={clsx(
         PLAYER_LIST_SURFACE_BASE_CLASS,
         PLAYER_EPG_LIST_ITEM_CLASS,
diff --git a/web-ui/src/i18n/player.ts b/web-ui/src/i18n/player.ts
index b6371b54..37e9ac14 100644
--- a/web-ui/src/i18n/player.ts
+++ b/web-ui/src/i18n/player.ts
@@ -22,7 +22,6 @@ const base: TranslationDict = {
   allChannels: "All",
   catchup: "Catchup",
   catchupSupported: "Catchup supported",
-  copyMediaLinkHint: "Middle-click to copy the media link",
   mediaLinkCopied: "Media link copied",
   copyMediaLinkFailed: "Could not copy the media link",
   copyMediaLinkUnavailable: "No media link available for this item",
@@ -155,7 +154,6 @@ const zhHans: TranslationDict = {
   allChannels: "全部",
   catchup: "回看",
   catchupSupported: "支持回看",
-  copyMediaLinkHint: "中键点击复制媒体直链",
   mediaLinkCopied: "已复制媒体直链",
   copyMediaLinkFailed: "复制媒体直链失败",
   copyMediaLinkUnavailable: "该项没有可复制的媒体直链",
@@ -288,7 +286,6 @@ const zhHant: TranslationDict = {
   allChannels: "全部",
   catchup: "回看",
   catchupSupported: "支援回看",
-  copyMediaLinkHint: "中鍵點擊複製媒體直鏈",
   mediaLinkCopied: "已複製媒體直鏈",
   copyMediaLinkFailed: "複製媒體直鏈失敗",
   copyMediaLinkUnavailable: "該項沒有可複製的媒體直鏈",

From 106baee33b29d40669eb69b06ef747d02e1a8cae Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 2 Sep 2026 10:22:51 +0000
Subject: [PATCH 5/8] fix(web-player): keep playseek when stripping $label from
 catchup URLs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Append-mode copy concatenated `$HD` onto the live path before the query.
Stripping treated `$HD?playseek=…` as one label and dropped the time range.

Co-authored-by: Stackie Jia <jsq2627@gmail.com>
---
 web-ui/src/lib/media-direct-link.test.ts | 31 ++++++++++++++++++++++++
 web-ui/src/lib/media-direct-link.ts      | 29 +++++++++++++++++++---
 2 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/web-ui/src/lib/media-direct-link.test.ts b/web-ui/src/lib/media-direct-link.test.ts
index 20726814..c32f6894 100644
--- a/web-ui/src/lib/media-direct-link.test.ts
+++ b/web-ui/src/lib/media-direct-link.test.ts
@@ -33,6 +33,15 @@ describe("stripPlaylistUrlLabel", () => {
     expect(stripPlaylistUrlLabel("http://example/ch$HD")).toBe("http://example/ch");
     expect(stripPlaylistUrlLabel(placeholderUrl)).toBe("http://example/ch?t=$" + "{utc}");
   });
+
+  it("keeps an appended catchup query after a path $label", () => {
+    expect(stripPlaylistUrlLabel("/Channel$HD?playseek=20260902100000-20260902120000")).toBe(
+      "/Channel?playseek=20260902100000-20260902120000",
+    );
+    expect(stripPlaylistUrlLabel("/Channel$HD&playseek=20260902100000-20260902120000")).toBe(
+      "/Channel&playseek=20260902100000-20260902120000",
+    );
+  });
 });
 
 describe("toAbsoluteMediaUrl", () => {
@@ -40,6 +49,9 @@ describe("toAbsoluteMediaUrl", () => {
     expect(toAbsoluteMediaUrl("/Test/Live Only$HD", "http://127.0.0.1:8080/")).toBe(
       "http://127.0.0.1:8080/Test/Live%20Only",
     );
+    expect(toAbsoluteMediaUrl("/Test/Live$HD?playseek=20260902100000-20260902120000", "http://127.0.0.1:8080/")).toBe(
+      "http://127.0.0.1:8080/Test/Live?playseek=20260902100000-20260902120000",
+    );
   });
 });
 
@@ -60,6 +72,25 @@ describe("getProgramMediaUrl", () => {
     expect(url).toBe("/Test/Catchup Channel/catchup?playseek=20260902100000-20260902120000");
   });
 
+  it("keeps playseek when append-mode catchup is concatenated onto a $label live URL", () => {
+    const start = new Date("2026-09-02T10:00:00.000Z");
+    const end = new Date("2026-09-02T12:00:00.000Z");
+    const ch = channel({
+      sources: [
+        {
+          url: "/Test/Catchup Channel$HD",
+          catchup: "append",
+          catchupSource: "?playseek={(b)YmdHMS|UTC}-{(e)YmdHMS|UTC}",
+          label: "HD",
+        },
+      ],
+    });
+
+    expect(getProgramMediaUrl(ch, { start, end }, 0, NOW)).toBe(
+      "/Test/Catchup Channel?playseek=20260902100000-20260902120000",
+    );
+  });
+
   it("pads programmes shorter than CATCHUP_MIN_DURATION_MS", () => {
     const start = new Date("2026-09-02T10:00:00.000Z");
     const end = new Date(start.getTime() + 5_000);
diff --git a/web-ui/src/lib/media-direct-link.ts b/web-ui/src/lib/media-direct-link.ts
index 58b8a7b1..d4cc3bf4 100644
--- a/web-ui/src/lib/media-direct-link.ts
+++ b/web-ui/src/lib/media-direct-link.ts
@@ -4,15 +4,32 @@ import { CATCHUP_MIN_DURATION_MS, type CatchupProgramBound } from "./catchup-win
 import { getLastSourceIndex } from "./player-storage";
 
 /**
- * Strip a trailing `$label` suffix the same way the server does.
+ * Strip a `$label` suffix the same way the server does for request paths.
  * `${...}` placeholders are left intact.
+ *
+ * Labels sit at the end of an M3U URL, or at the end of the path after
+ * catchup="append" concatenates a query. Do not treat `$HD?playseek=…` as one
+ * label — that would drop the time range.
  */
 export function stripPlaylistUrlLabel(url: string): string {
   for (let i = url.length - 1; i >= 0; i--) {
     if (url[i] !== "$") continue;
     if (i === url.length - 1) continue;
     if (url[i + 1] === "{") continue;
-    return url.slice(0, i);
+
+    let labelEnd = i + 1;
+    while (
+      labelEnd < url.length &&
+      url[labelEnd] !== "?" &&
+      url[labelEnd] !== "#" &&
+      url[labelEnd] !== "&" &&
+      url[labelEnd] !== "/"
+    ) {
+      labelEnd++;
+    }
+    if (labelEnd < url.length && url[labelEnd] === "/") continue;
+    if (labelEnd === i + 1) continue;
+    return url.slice(0, i) + url.slice(labelEnd);
   }
   return url;
 }
@@ -89,7 +106,13 @@ export function getProgramMediaUrl(
   if (catchupSource) {
     const start = program.start;
     const end = new Date(Math.max(program.end.getTime(), start.getTime() + CATCHUP_MIN_DURATION_MS));
-    return toAbsoluteMediaUrl(buildCatchupUrl(catchupSource, start, end, now));
+    // Strip `$label` from the live URL before append-mode concatenation so the
+    // playseek suffix is not glued onto `$HD`.
+    const sourceForCopy: Source = {
+      ...catchupSource,
+      url: stripPlaylistUrlLabel(catchupSource.url),
+    };
+    return toAbsoluteMediaUrl(buildCatchupUrl(sourceForCopy, start, end, now));
   }
   if (program.start.getTime() <= now.getTime() && program.end.getTime() > now.getTime()) {
     return getChannelLiveMediaUrl(channel, preferredIndex);

From c28abdef5c0930ca985993c2c6fdaebe77fbe951 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 2 Sep 2026 10:38:06 +0000
Subject: [PATCH 6/8] feat(http): honor r2h-filename for MPEG-TS downloads

Copied media links now carry a friendly r2h-filename query parameter.
Multicast and RTSP MPEG-TS responses emit Content-Disposition so browsers
save the file with a .ts name. The parameter is stripped before upstream
requests and ignored by HTTP/HLS proxying.

Co-authored-by: Stackie Jia <jsq2627@gmail.com>
---
 docs/en/guide/url-formats.md             |  14 +++
 docs/en/guide/web-player.md              |   2 +
 docs/guide/url-formats.md                |  14 +++
 docs/guide/web-player.md                 |   2 +
 e2e/test_http_proxy.py                   |  25 ++++
 e2e/test_multicast.py                    | 112 ++++++++++++++++-
 e2e/test_rtsp_transport.py               |  45 +++++++
 src/http.c                               | 151 +++++++++++++++++++++++
 src/http.h                               |  22 ++++
 src/service.c                            |   3 +
 src/stream.c                             |  34 ++++-
 web-ui/src/lib/media-direct-link.test.ts | 109 +++++++++++++---
 web-ui/src/lib/media-direct-link.ts      |  93 +++++++++++++-
 13 files changed, 606 insertions(+), 20 deletions(-)

diff --git a/docs/en/guide/url-formats.md b/docs/en/guide/url-formats.md
index 34c0693a..7f499bac 100644
--- a/docs/en/guide/url-formats.md
+++ b/docs/en/guide/url-formats.md
@@ -38,6 +38,7 @@ http://192.168.1.1:5140/rtp/239.253.64.120:5140?fcc=10.255.14.152:15970&r2h-ifna
 - **fec** (optional): FEC (Forward Error Correction) port number, used to receive FEC redundant packets for packet loss recovery
 - **r2h-ifname** (optional): Specify the upstream network interface to use (overrides global configuration)
 - **r2h-ifname-fcc** (optional): Specify the upstream network interface for FCC (overrides global configuration)
+- **r2h-filename** (optional): Download filename. See [Download Filename](#download-filename)
 
 ### Use Cases
 
@@ -106,6 +107,19 @@ RTSP, standard multicast, and FCC streams carry the following `R2H-*` metadata i
 | `R2H-FCC-Type` | Configured FCC protocol: `telecom` or `huawei`. |
 | `R2H-FCC-Status` | `active` when playback starts from FCC unicast; `fallback` when it starts from multicast. |
 
+## Download Filename
+
+Multicast RTP and RTSP MPEG-TS responses honor the `r2h-filename` query parameter. When it is non-empty, rtp2httpd sends `Content-Disposition: attachment` so browsers save the download under that name. The server strips path separators and control characters, and appends `.ts` when the suffix is missing.
+
+This parameter is local to rtp2httpd and is not forwarded upstream. HTTP/HLS reverse proxy requests strip it before the upstream fetch and do not set `Content-Disposition`.
+
+```url
+http://192.168.1.1:5140/rtp/239.253.64.120:5140?r2h-filename=CCTV-1.ts
+http://192.168.1.1:5140/rtsp/iptv.example.com:554/channel1?playseek=20240101120000-20240101130000&r2h-filename=CCTV-1_News_20240101-120000_20240101-130000.ts
+```
+
+The built-in web player adds this parameter automatically when you copy a media link.
+
 ## HTTP Reverse Proxy
 
 ```url
diff --git a/docs/en/guide/web-player.md b/docs/en/guide/web-player.md
index 913f34a4..46b93a2f 100644
--- a/docs/en/guide/web-player.md
+++ b/docs/en/guide/web-player.md
@@ -49,6 +49,8 @@ Middle-click a channel in the channel list to copy that channel's live URL for t
 
 The copied value is a directly requestable HTTP media URL, which you can download with FFmpeg, N_m3u8DL-RE, IDM, or open in a third-party player. For multi-source channels, the most recently used source is copied. If the current page includes `r2h-token`, the copied link includes that parameter as well.
 
+Multicast and RTSP links also include an `r2h-filename` query parameter. Its value is a `.ts` filename built from the channel name, source label, program title, and time range, so a browser download uses that name. See [URL Formats](/en/guide/url-formats#download-filename).
+
 > [!NOTE]
 > An on-air program with no catch-up source copies the live URL. A program that has not started and has no catch-up source cannot be copied.
 
diff --git a/docs/guide/url-formats.md b/docs/guide/url-formats.md
index 07e3057a..6f8e1f6e 100644
--- a/docs/guide/url-formats.md
+++ b/docs/guide/url-formats.md
@@ -38,6 +38,7 @@ http://192.168.1.1:5140/rtp/239.253.64.120:5140?fcc=10.255.14.152:15970&r2h-ifna
 - **fec**（可选）：FEC 前向纠错端口号，用于接收 FEC 冗余数据包来恢复丢包
 - **r2h-ifname**（可选）：指定使用的上游网络接口（覆盖全局配置）
 - **r2h-ifname-fcc**（可选）：指定 FCC 使用的上游网络接口（覆盖全局配置）
+- **r2h-filename**（可选）：下载文件名，详见 [下载文件名](#下载文件名)
 
 ### 使用场景
 
@@ -106,6 +107,19 @@ RTSP、普通组播和 FCC 流会在 HTTP Headers 带上以下 `R2H-*` Metadata
 | `R2H-FCC-Type` | 已配置的 FCC 协议：`telecom` 或 `huawei`。 |
 | `R2H-FCC-Status` | 从 FCC 单播起播为 `active`；从组播起播为 `fallback`。 |
 
+## 下载文件名
+
+组播 RTP 和 RTSP 的 MPEG-TS 响应支持 `r2h-filename` 查询参数。参数非空时，rtp2httpd 会输出 `Content-Disposition: attachment`，让浏览器按指定文件名保存下载。服务端会去掉路径分隔符和控制字符，并在缺少后缀时补上 `.ts`。
+
+该参数只作用于 rtp2httpd 自身，不会转发给上游。HTTP/HLS 反向代理会在转发前剥离该参数，也不会设置 `Content-Disposition`。
+
+```url
+http://192.168.1.1:5140/rtp/239.253.64.120:5140?r2h-filename=CCTV-1.ts
+http://192.168.1.1:5140/rtsp/iptv.example.com:554/channel1?playseek=20240101120000-20240101130000&r2h-filename=CCTV-1_新闻联播_20240101-120000_20240101-130000.ts
+```
+
+内置 Web 播放器复制媒体直链时会自动带上该参数。
+
 ## HTTP 反向代理
 
 ```url
diff --git a/docs/guide/web-player.md b/docs/guide/web-player.md
index 2cf71cd9..742e6c44 100644
--- a/docs/guide/web-player.md
+++ b/docs/guide/web-player.md
@@ -49,6 +49,8 @@ http://服务器地址:端口/player#CCTV-1
 
 复制得到的是可直接请求的 HTTP 媒体地址，可用于 FFmpeg、N_m3u8DL-RE、IDM 等工具下载或在第三方播放器中打开。多线路频道会复制最近一次使用的线路；若当前页面带有 `r2h-token`，复制的链接也会带上该参数。
 
+组播和 RTSP 直链还会带上 `r2h-filename` 查询参数，值为频道名、线路标签、节目名和时间范围组成的 `.ts` 文件名。用浏览器打开并触发下载时，会按该文件名保存。详见 [URL 格式说明](./url-formats.md#下载文件名)。
+
 > [!NOTE]
 > 正在播出且没有回看源的节目会复制直播地址。尚未开始且没有回看源的节目无法复制。
 
diff --git a/e2e/test_http_proxy.py b/e2e/test_http_proxy.py
index 92d4a3a4..18540144 100644
--- a/e2e/test_http_proxy.py
+++ b/e2e/test_http_proxy.py
@@ -197,6 +197,31 @@ def test_r2h_token_not_forwarded(self, shared_r2h, token_param):
         finally:
             upstream.stop()
 
+    def test_r2h_filename_not_forwarded(self, shared_r2h):
+        """r2h-filename is local download metadata and should be stripped before upstream HTTP."""
+        upstream = MockHTTPUpstream(
+            routes={
+                "/search": {"status": 200, "body": b"found"},
+            }
+        )
+        upstream.start()
+        try:
+            status, headers, body = http_get(
+                "127.0.0.1",
+                shared_r2h.port,
+                f"/http/127.0.0.1:{upstream.port}/search?r2h-filename=clip.ts&q=test",
+                timeout=5.0,
+            )
+            assert status == 200
+            assert body == b"found"
+            assert "Content-Disposition" not in {key.lower() for key in headers}
+            assert upstream.requests_log, "expected upstream HTTP request"
+            upstream_path = upstream.requests_log[0]["path"]
+            assert "r2h-filename" not in upstream_path.lower()
+            assert "q=test" in upstream_path
+        finally:
+            upstream.stop()
+
 
 # ---------------------------------------------------------------------------
 # Upstream unreachable
diff --git a/e2e/test_multicast.py b/e2e/test_multicast.py
index b02db99f..1ab8b110 100644
--- a/e2e/test_multicast.py
+++ b/e2e/test_multicast.py
@@ -243,7 +243,7 @@ def test_head_rtp(self, r2h_binary):
         )
         try:
             r2h.start()
-            from helpers import http_request
+            from helpers import get_header, http_request
 
             status, hdrs, body = http_request(
                 "127.0.0.1",
@@ -257,6 +257,7 @@ def test_head_rtp(self, r2h_binary):
             assert hdrs.get("R2H-Upstream-Protocol") == "multicast"
             assert "R2H-Upstream-Payload" not in hdrs
             assert "R2H-FCC-Status" not in hdrs
+            assert get_header(hdrs, "Content-Disposition") == ""
             exposed = {name.strip() for name in hdrs["Access-Control-Expose-Headers"].split(",")}
             assert exposed == {
                 "R2H-Upstream-Protocol",
@@ -271,6 +272,115 @@ def test_head_rtp(self, r2h_binary):
         finally:
             r2h.stop()
 
+    def test_head_rtp_sets_content_disposition_from_filename(self, r2h_binary):
+        port = find_free_port()
+        mcast_port = find_free_udp_port()
+        r2h = R2HProcess(
+            r2h_binary,
+            port,
+            extra_args=["-v", "4", "-m", "100"],
+        )
+        try:
+            r2h.start()
+            from helpers import get_header, http_request
+
+            status, hdrs, body = http_request(
+                "127.0.0.1",
+                port,
+                "HEAD",
+                f"/rtp/{MCAST_ADDR}:{mcast_port}?r2h-filename=CCTV-1.ts",
+                timeout=3.0,
+            )
+            assert status == 200
+            assert body == b""
+            disposition = get_header(hdrs, "Content-Disposition")
+            assert disposition.startswith("attachment;")
+            assert 'filename="CCTV-1.ts"' in disposition
+        finally:
+            r2h.stop()
+
+    def test_head_rtp_sanitizes_filename_header_injection(self, r2h_binary):
+        port = find_free_port()
+        mcast_port = find_free_udp_port()
+        r2h = R2HProcess(
+            r2h_binary,
+            port,
+            extra_args=["-v", "4", "-m", "100"],
+        )
+        try:
+            r2h.start()
+            from helpers import get_header, http_request
+
+            status, hdrs, body = http_request(
+                "127.0.0.1",
+                port,
+                "HEAD",
+                f"/rtp/{MCAST_ADDR}:{mcast_port}?r2h-filename=foo%0d%0aSet-Cookie:%20evil",
+                timeout=3.0,
+            )
+            assert status == 200
+            assert body == b""
+            disposition = get_header(hdrs, "Content-Disposition")
+            assert "Set-Cookie" not in disposition
+            assert "\r" not in disposition
+            assert "\n" not in disposition
+            assert 'filename="foo_Set-Cookie_ evil.ts"' in disposition
+        finally:
+            r2h.stop()
+
+    def test_head_rtp_empty_filename_omits_content_disposition(self, r2h_binary):
+        port = find_free_port()
+        mcast_port = find_free_udp_port()
+        r2h = R2HProcess(
+            r2h_binary,
+            port,
+            extra_args=["-v", "4", "-m", "100"],
+        )
+        try:
+            r2h.start()
+            from helpers import get_header, http_request
+
+            status, hdrs, body = http_request(
+                "127.0.0.1",
+                port,
+                "HEAD",
+                f"/rtp/{MCAST_ADDR}:{mcast_port}?r2h-filename=",
+                timeout=3.0,
+            )
+            assert status == 200
+            assert body == b""
+            assert get_header(hdrs, "Content-Disposition") == ""
+        finally:
+            r2h.stop()
+
+    def test_head_rtp_utf8_filename_uses_rfc5987(self, r2h_binary):
+        port = find_free_port()
+        mcast_port = find_free_udp_port()
+        r2h = R2HProcess(
+            r2h_binary,
+            port,
+            extra_args=["-v", "4", "-m", "100"],
+        )
+        try:
+            r2h.start()
+            from helpers import get_header, http_request
+
+            status, hdrs, body = http_request(
+                "127.0.0.1",
+                port,
+                "HEAD",
+                f"/rtp/{MCAST_ADDR}:{mcast_port}?r2h-filename=%E6%B5%8B%E8%AF%95.ts",
+                timeout=3.0,
+            )
+            assert status == 200
+            assert body == b""
+            disposition = get_header(hdrs, "Content-Disposition")
+            assert disposition.startswith("attachment;")
+            assert "filename*=UTF-8''" in disposition
+            assert "%E6%B5%8B%E8%AF%95.ts" in disposition
+        finally:
+            r2h.stop()
+
 
 class TestSnapshotFallbackMetadata:
     """A failed JPEG capture must fall back to one MPEG-TS response."""
diff --git a/e2e/test_rtsp_transport.py b/e2e/test_rtsp_transport.py
index fdfaf9f8..e14c3a3a 100644
--- a/e2e/test_rtsp_transport.py
+++ b/e2e/test_rtsp_transport.py
@@ -120,6 +120,51 @@ def test_head_stops_after_describe(self, shared_r2h):
         finally:
             rtsp.stop()
 
+    def test_head_sets_content_disposition_from_filename(self, shared_r2h):
+        rtsp = MockRTSPServer()
+        rtsp.start()
+        try:
+            status, headers, body = http_request(
+                "127.0.0.1",
+                shared_r2h.port,
+                "HEAD",
+                f"/rtsp/127.0.0.1:{rtsp.port}/stream?r2h-filename=News_1200.ts",
+                timeout=10.0,
+            )
+            assert status == 200
+            assert body == b""
+            disposition = get_header(headers, "Content-Disposition")
+            assert disposition.startswith("attachment;")
+            assert 'filename="News_1200.ts"' in disposition
+            for request in rtsp.requests_detailed:
+                assert "r2h-filename" not in request["uri"].lower(), (
+                    f"r2h-filename leaked into upstream {request['method']} URI: {request['uri']}"
+                )
+        finally:
+            rtsp.stop()
+
+    def test_r2h_filename_does_not_leak_to_rtsp_upstream(self, shared_r2h):
+        rtsp = MockRTSPServer(num_packets=500)
+        rtsp.start()
+        try:
+            status, headers, body = stream_get(
+                "127.0.0.1",
+                shared_r2h.port,
+                f"/rtsp/127.0.0.1:{rtsp.port}/stream?r2h-filename=Catchup.ts",
+                read_bytes=4096,
+                timeout=_STREAM_TIMEOUT,
+            )
+            assert status == 200
+            assert body
+            assert 'filename="Catchup.ts"' in headers["content-disposition"]
+            assert rtsp.requests_detailed, "expected RTSP requests"
+            for request in rtsp.requests_detailed:
+                assert "r2h-filename" not in request["uri"].lower(), (
+                    f"r2h-filename leaked into upstream {request['method']} URI: {request['uri']}"
+                )
+        finally:
+            rtsp.stop()
+
     def test_head_parses_clock_form_npt_duration(self, shared_r2h):
         sdp = (
             "v=0\r\no=- 0 0 IN IP4 127.0.0.1\r\ns=T\r\n"
diff --git a/src/http.c b/src/http.c
index 377b3421..0cbd7f56 100644
--- a/src/http.c
+++ b/src/http.c
@@ -157,6 +157,157 @@ char *http_url_encode(const char *str) {
   return encoded;
 }
 
+static int http_filename_forbidden_char(unsigned char c) {
+  return c < 0x20 || c == 0x7f || c == '/' || c == '\\' || c == ':' || c == '*' || c == '?' || c == '"' || c == '<' ||
+         c == '>' || c == '|';
+}
+
+static size_t http_utf8_char_len(unsigned char c) {
+  if ((c & 0x80) == 0)
+    return 1;
+  if ((c & 0xE0) == 0xC0)
+    return 2;
+  if ((c & 0xF0) == 0xE0)
+    return 3;
+  if ((c & 0xF8) == 0xF0)
+    return 4;
+  return 0;
+}
+
+static int http_filename_has_ts_suffix(const char *name, size_t len) {
+  return len >= 3 && strcasecmp(name + len - 3, ".ts") == 0;
+}
+
+int http_sanitize_download_filename(const char *input, char *output, size_t output_size) {
+  char tmp[HTTP_DOWNLOAD_FILENAME_MAX + 8];
+  size_t out_len = 0;
+  size_t i = 0;
+  int pending_sep = 1;
+  size_t name_len;
+
+  if (!input || !output || output_size < 5)
+    return -1;
+
+  while (input[i] && out_len < HTTP_DOWNLOAD_FILENAME_MAX) {
+    unsigned char c = (unsigned char)input[i];
+    size_t char_len;
+
+    if (http_filename_forbidden_char(c)) {
+      if (!pending_sep && out_len + 1 <= HTTP_DOWNLOAD_FILENAME_MAX) {
+        tmp[out_len++] = '_';
+        pending_sep = 1;
+      }
+      i++;
+      continue;
+    }
+
+    char_len = http_utf8_char_len(c);
+    if (char_len == 0) {
+      i++;
+      continue;
+    }
+    if (out_len + char_len > HTTP_DOWNLOAD_FILENAME_MAX)
+      break;
+
+    memcpy(tmp + out_len, input + i, char_len);
+    out_len += char_len;
+    i += char_len;
+    pending_sep = (c == '_' || c == ' ' || c == '.');
+  }
+
+  while (out_len > 0) {
+    char tail = tmp[out_len - 1];
+    if (tail == '_' || tail == '.' || tail == ' ')
+      out_len--;
+    else
+      break;
+  }
+
+  if (out_len == 0)
+    return -1;
+
+  if (!http_filename_has_ts_suffix(tmp, out_len)) {
+    if (out_len + 3 >= sizeof(tmp))
+      out_len = HTTP_DOWNLOAD_FILENAME_MAX - 3;
+    tmp[out_len++] = '.';
+    tmp[out_len++] = 't';
+    tmp[out_len++] = 's';
+  }
+  tmp[out_len] = '\0';
+
+  name_len = strlen(tmp);
+  if (name_len + 1 > output_size)
+    return -1;
+  memcpy(output, tmp, name_len + 1);
+  return 0;
+}
+
+static int http_is_rfc5987_attr_char(unsigned char c) {
+  return isalnum((int)c) || c == '!' || c == '#' || c == '$' || c == '&' || c == '+' || c == '-' || c == '.' ||
+         c == '^' || c == '_' || c == '`' || c == '|' || c == '~';
+}
+
+int http_build_content_disposition_header(const char *filename, char *output, size_t output_size) {
+  char ascii[HTTP_DOWNLOAD_FILENAME_MAX + 8];
+  char encoded[(HTTP_DOWNLOAD_FILENAME_MAX + 8) * 3];
+  static const char hex_chars[] = "0123456789ABCDEF";
+  size_t i;
+  size_t ascii_len = 0;
+  size_t encoded_len = 0;
+  int has_non_ascii = 0;
+  int ascii_has_alnum = 0;
+  int written;
+
+  if (!filename || !filename[0] || !output || output_size == 0)
+    return -1;
+
+  for (i = 0; filename[i]; i++) {
+    unsigned char c = (unsigned char)filename[i];
+    if (c >= 0x80) {
+      has_non_ascii = 1;
+      if (ascii_len + 1 < sizeof(ascii))
+        ascii[ascii_len++] = '_';
+    } else if (c != '"') {
+      if (ascii_len + 1 < sizeof(ascii))
+        ascii[ascii_len++] = (char)c;
+      if (isalnum((int)c))
+        ascii_has_alnum = 1;
+    }
+  }
+  ascii[ascii_len] = '\0';
+  if (!ascii_has_alnum)
+    snprintf(ascii, sizeof(ascii), "download.ts");
+
+  if (!has_non_ascii) {
+    written = snprintf(output, output_size, "Content-Disposition: attachment; filename=\"%s\"\r\n", filename);
+    if (written < 0 || (size_t)written >= output_size)
+      return -1;
+    return written;
+  }
+
+  for (i = 0; filename[i]; i++) {
+    unsigned char c = (unsigned char)filename[i];
+    if (http_is_rfc5987_attr_char(c)) {
+      if (encoded_len + 1 >= sizeof(encoded))
+        return -1;
+      encoded[encoded_len++] = (char)c;
+    } else {
+      if (encoded_len + 3 >= sizeof(encoded))
+        return -1;
+      encoded[encoded_len++] = '%';
+      encoded[encoded_len++] = hex_chars[c >> 4];
+      encoded[encoded_len++] = hex_chars[c & 0x0F];
+    }
+  }
+  encoded[encoded_len] = '\0';
+
+  written = snprintf(output, output_size, "Content-Disposition: attachment; filename=\"%s\"; filename*=UTF-8''%s\r\n",
+                     ascii, encoded);
+  if (written < 0 || (size_t)written >= output_size)
+    return -1;
+  return written;
+}
+
 int http_build_r2h_token_cookie_header(char *buffer, size_t buffer_size, const char *path) {
   char *encoded_token;
   int written;
diff --git a/src/http.h b/src/http.h
index 444f08e4..43dd17a4 100644
--- a/src/http.h
+++ b/src/http.h
@@ -117,6 +117,28 @@ int http_url_decode(char *str);
  */
 char *http_url_encode(const char *str);
 
+/* Max sanitized download filename (excluding NUL), including the .ts suffix. */
+#ifndef HTTP_DOWNLOAD_FILENAME_MAX
+#define HTTP_DOWNLOAD_FILENAME_MAX 180
+#endif
+
+/**
+ * Sanitize a client-supplied download filename for Content-Disposition.
+ * Replaces path separators / control characters, truncates on a UTF-8
+ * character boundary, and ensures a .ts suffix.
+ *
+ * @return 0 on success, -1 if input is empty after sanitizing or buffers are invalid
+ */
+int http_sanitize_download_filename(const char *input, char *output, size_t output_size);
+
+/**
+ * Build a Content-Disposition header line including the trailing CRLF.
+ * Uses RFC 6266 `filename` plus RFC 5987 `filename*` when the name is not ASCII.
+ *
+ * @return Bytes written, or -1 on error / truncation
+ */
+int http_build_content_disposition_header(const char *filename, char *output, size_t output_size);
+
 /**
  * Build a Set-Cookie header for the configured r2h-token.
  * The cookie value is URL-encoded so token characters such as ';' remain safe
diff --git a/src/service.c b/src/service.c
index 5a92191a..702c5033 100644
--- a/src/service.c
+++ b/src/service.c
@@ -1235,6 +1235,7 @@ service_t *service_create_from_http_url(const char *http_url) {
                                 &result->seek_mode_tz_offset_seconds, &result->seek_mode_window_seconds);
     service_extract_ifname_params(query_start, &result->ifname, &result->ifname_fcc);
     service_strip_query_param(query_start, "r2h-token");
+    service_strip_query_param(query_start, "r2h-filename");
   }
 
   logger(LOG_DEBUG, "Created HTTP proxy service: %s -> %s", http_url, result->http_url);
@@ -1325,6 +1326,7 @@ service_t *service_create_from_rtsp_url(const char *http_url) {
     }
     service_extract_ifname_params(query_start, &ifname, &ifname_fcc);
     service_strip_query_param(query_start, "r2h-token");
+    service_strip_query_param(query_start, "r2h-filename");
   }
 
   /* Allocate service structure */
@@ -1643,6 +1645,7 @@ service_t *service_create_from_rtp_url(const char *http_url) {
     char *qstart = strchr(url_part, '?');
     service_extract_ifname_params(qstart, &result->ifname, &result->ifname_fcc);
     service_strip_query_param(qstart, "r2h-token");
+    service_strip_query_param(qstart, "r2h-filename");
   }
 
   /* Build and store full RTP URL (rtp://) - r2h-* auth/control params stripped */
diff --git a/src/stream.c b/src/stream.c
index 7e653f2a..064e4166 100644
--- a/src/stream.c
+++ b/src/stream.c
@@ -23,7 +23,7 @@
 #include <sys/socket.h>
 #include <unistd.h>
 
-#define STREAM_METADATA_HEADERS_SIZE 1024
+#define STREAM_METADATA_HEADERS_SIZE 1536
 #define TS_PACKET_SIZE 188
 #define TS_SYNC_BYTE 0x47
 
@@ -200,6 +200,35 @@ static void stream_metadata_note_media(stream_context_t *ctx, int packet_type, c
   }
 }
 
+static int stream_append_download_filename_header(connection_t *conn, char *headers, size_t headers_size,
+                                                  size_t *length) {
+  const char *query;
+  char raw[768];
+  char sanitized[HTTP_DOWNLOAD_FILENAME_MAX + 8];
+  char line[768];
+
+  if (!conn)
+    return 0;
+
+  query = strchr(conn->http_req.url, '?');
+  if (!query)
+    return 0;
+  if (http_parse_query_param(query + 1, "r2h-filename", raw, sizeof(raw)) != 0)
+    return 0;
+  if (raw[0] == '\0')
+    return 0;
+  if (http_sanitize_download_filename(raw, sanitized, sizeof(sanitized)) != 0)
+    return 0;
+  if (http_build_content_disposition_header(sanitized, line, sizeof(line)) < 0)
+    return 0;
+  /* Omit the download name rather than dropping the rest of the metadata. */
+  if (stream_metadata_append_raw(headers, headers_size, length, line) < 0) {
+    logger(LOG_DEBUG, "Stream: Content-Disposition header omitted (buffer full)");
+    return 0;
+  }
+  return 0;
+}
+
 void stream_send_http_headers(connection_t *conn, const char *content_type, const char *extra_headers) {
   stream_metadata_t *metadata;
   char headers[STREAM_METADATA_HEADERS_SIZE];
@@ -217,6 +246,9 @@ void stream_send_http_headers(connection_t *conn, const char *content_type, cons
   if (extra_headers && extra_headers[0])
     failed |= stream_metadata_append_raw(headers, sizeof(headers), &length, extra_headers) < 0;
 
+  if (content_type && strcmp(content_type, "video/mp2t") == 0)
+    stream_append_download_filename_header(conn, headers, sizeof(headers), &length);
+
   failed |= stream_metadata_append_enum(headers, sizeof(headers), &length, STREAM_HDR_UPSTREAM_PROTOCOL,
                                         stream_upstream_protocol_values, ARRAY_SIZE(stream_upstream_protocol_values),
                                         metadata->upstream_protocol) < 0;
diff --git a/web-ui/src/lib/media-direct-link.test.ts b/web-ui/src/lib/media-direct-link.test.ts
index c32f6894..ddb3d108 100644
--- a/web-ui/src/lib/media-direct-link.test.ts
+++ b/web-ui/src/lib/media-direct-link.test.ts
@@ -3,14 +3,38 @@ import type { Channel } from "../types/player";
 import { buildCatchupUrl } from "./catchup-url";
 import { CATCHUP_MIN_DURATION_MS } from "./catchup-windows";
 import {
+  buildMediaDownloadFilename,
+  formatMediaDownloadTimestamp,
   getChannelLiveMediaUrl,
   getProgramMediaUrl,
+  sanitizeMediaDownloadFilename,
   stripPlaylistUrlLabel,
   toAbsoluteMediaUrl,
 } from "./media-direct-link";
 
 const NOW = new Date("2026-09-02T12:00:00.000Z");
 
+function stripFilenameParam(url: string | null): string | null {
+  if (!url) return url;
+  const hashIndex = url.indexOf("#");
+  const hash = hashIndex === -1 ? "" : url.slice(hashIndex);
+  const withoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+  const qIndex = withoutHash.indexOf("?");
+  if (qIndex === -1) return url;
+  const path = withoutHash.slice(0, qIndex);
+  const params = withoutHash
+    .slice(qIndex + 1)
+    .split("&")
+    .filter((part) => !part.toLowerCase().startsWith("r2h-filename="));
+  return (params.length > 0 ? `${path}?${params.join("&")}` : path) + hash;
+}
+
+function copiedFilename(url: string | null): string | null {
+  if (!url) return null;
+  const match = url.match(/[?&]r2h-filename=([^&#]*)/i);
+  return match ? decodeURIComponent(match[1].replace(/\+/g, " ")) : null;
+}
+
 function channel(overrides: Partial<Channel> = {}): Channel {
   return {
     id: "1",
@@ -55,9 +79,38 @@ describe("toAbsoluteMediaUrl", () => {
   });
 });
 
+describe("sanitizeMediaDownloadFilename", () => {
+  it("replaces forbidden characters, collapses separators, and forces a .ts suffix", () => {
+    expect(sanitizeMediaDownloadFilename("CCTV-1 / 高清")).toBe("CCTV-1 _ 高清.ts");
+    expect(sanitizeMediaDownloadFilename("news:live*.ts")).toBe("news_live_.ts");
+    expect(sanitizeMediaDownloadFilename("foo/bar\\baz:qux")).toBe("foo_bar_baz_qux.ts");
+    expect(sanitizeMediaDownloadFilename("   ")).toBe("download.ts");
+  });
+});
+
+describe("buildMediaDownloadFilename", () => {
+  it("joins channel, optional label, title, and local time range", () => {
+    const start = new Date("2026-09-02T10:00:00.000Z");
+    const end = new Date("2026-09-02T12:00:00.000Z");
+    expect(
+      buildMediaDownloadFilename({
+        channelName: "Catchup Channel",
+        sourceLabel: "HD",
+        programTitle: "Morning News",
+        start,
+        end,
+      }),
+    ).toBe(
+      `Catchup Channel_HD_Morning News_${formatMediaDownloadTimestamp(start)}_${formatMediaDownloadTimestamp(end)}.ts`,
+    );
+  });
+});
+
 describe("getChannelLiveMediaUrl", () => {
-  it("returns the live source URL", () => {
-    expect(getChannelLiveMediaUrl(channel(), 0)).toBe("/Test/Catchup Channel");
+  it("returns the live source URL with a download filename", () => {
+    const url = getChannelLiveMediaUrl(channel(), 0);
+    expect(stripFilenameParam(url)).toBe("/Test/Catchup Channel");
+    expect(copiedFilename(url)).toBe("Catchup Channel.ts");
   });
 });
 
@@ -66,10 +119,18 @@ describe("getProgramMediaUrl", () => {
     const start = new Date("2026-09-02T10:00:00.000Z");
     const end = new Date("2026-09-02T12:00:00.000Z");
     const ch = channel();
-    const url = getProgramMediaUrl(ch, { start, end }, 0, NOW);
+    const url = getProgramMediaUrl(ch, { start, end, title: "Morning News" }, 0, NOW);
 
-    expect(url).toBe(buildCatchupUrl(ch.sources[0], start, end, NOW));
-    expect(url).toBe("/Test/Catchup Channel/catchup?playseek=20260902100000-20260902120000");
+    expect(stripFilenameParam(url)).toBe(buildCatchupUrl(ch.sources[0], start, end, NOW));
+    expect(stripFilenameParam(url)).toBe("/Test/Catchup Channel/catchup?playseek=20260902100000-20260902120000");
+    expect(copiedFilename(url)).toBe(
+      buildMediaDownloadFilename({
+        channelName: "Catchup Channel",
+        programTitle: "Morning News",
+        start,
+        end,
+      }),
+    );
   });
 
   it("keeps playseek when append-mode catchup is concatenated onto a $label live URL", () => {
@@ -85,9 +146,16 @@ describe("getProgramMediaUrl", () => {
         },
       ],
     });
+    const url = getProgramMediaUrl(ch, { start, end }, 0, NOW);
 
-    expect(getProgramMediaUrl(ch, { start, end }, 0, NOW)).toBe(
-      "/Test/Catchup Channel?playseek=20260902100000-20260902120000",
+    expect(stripFilenameParam(url)).toBe("/Test/Catchup Channel?playseek=20260902100000-20260902120000");
+    expect(copiedFilename(url)).toBe(
+      buildMediaDownloadFilename({
+        channelName: "Catchup Channel",
+        sourceLabel: "HD",
+        start,
+        end,
+      }),
     );
   });
 
@@ -96,21 +164,34 @@ describe("getProgramMediaUrl", () => {
     const end = new Date(start.getTime() + 5_000);
     const ch = channel();
     const paddedEnd = new Date(start.getTime() + CATCHUP_MIN_DURATION_MS);
+    const url = getProgramMediaUrl(ch, { start, end }, 0, NOW);
 
-    expect(getProgramMediaUrl(ch, { start, end }, 0, NOW)).toBe(buildCatchupUrl(ch.sources[0], start, paddedEnd, NOW));
+    expect(stripFilenameParam(url)).toBe(buildCatchupUrl(ch.sources[0], start, paddedEnd, NOW));
+    expect(copiedFilename(url)).toBe(
+      buildMediaDownloadFilename({
+        channelName: "Catchup Channel",
+        start,
+        end: paddedEnd,
+      }),
+    );
   });
 
   it("falls back to the live URL for an on-air programme without catchup", () => {
     const liveOnly = channel({
       sources: [{ url: "/Test/Live Only" }],
     });
-    const url = getProgramMediaUrl(
-      liveOnly,
-      { start: new Date("2026-09-02T11:00:00.000Z"), end: new Date("2026-09-02T13:00:00.000Z") },
-      0,
-      NOW,
+    const start = new Date("2026-09-02T11:00:00.000Z");
+    const end = new Date("2026-09-02T13:00:00.000Z");
+    const url = getProgramMediaUrl(liveOnly, { start, end, title: "Live Show" }, 0, NOW);
+    expect(stripFilenameParam(url)).toBe("/Test/Live Only");
+    expect(copiedFilename(url)).toBe(
+      buildMediaDownloadFilename({
+        channelName: "Catchup Channel",
+        programTitle: "Live Show",
+        start,
+        end,
+      }),
     );
-    expect(url).toBe("/Test/Live Only");
   });
 
   it("returns null for a past programme without catchup", () => {
diff --git a/web-ui/src/lib/media-direct-link.ts b/web-ui/src/lib/media-direct-link.ts
index d4cc3bf4..02c134f5 100644
--- a/web-ui/src/lib/media-direct-link.ts
+++ b/web-ui/src/lib/media-direct-link.ts
@@ -79,6 +79,68 @@ export function toAbsoluteMediaUrl(
   return withPageAuthToken(absolute);
 }
 
+const FILENAME_FORBIDDEN_CHARS = new Set(["\\", "/", ":", "*", "?", '"', "<", ">", "|"]);
+const MEDIA_DOWNLOAD_FILENAME_MAX = 180;
+
+function replaceForbiddenFilenameChars(name: string): string {
+  let result = "";
+  for (const ch of name) {
+    const code = ch.charCodeAt(0);
+    result += code < 32 || code === 127 || FILENAME_FORBIDDEN_CHARS.has(ch) ? "_" : ch;
+  }
+  return result;
+}
+
+function pad2(value: number): string {
+  return value.toString().padStart(2, "0");
+}
+
+/** Local `yyyyMMdd-HHmmss` for download names that match the on-screen EPG clock. */
+export function formatMediaDownloadTimestamp(date: Date): string {
+  return `${date.getFullYear()}${pad2(date.getMonth() + 1)}${pad2(date.getDate())}-${pad2(date.getHours())}${pad2(date.getMinutes())}${pad2(date.getSeconds())}`;
+}
+
+export function sanitizeMediaDownloadFilename(name: string): string {
+  let sanitized = replaceForbiddenFilenameChars(name).replace(/\s+/g, " ").trim();
+  sanitized = sanitized.replace(/_+/g, "_").replace(/[.\s_]+$/g, "");
+  if (!sanitized) sanitized = "download";
+  if (sanitized.length > MEDIA_DOWNLOAD_FILENAME_MAX - 3) {
+    sanitized = sanitized.slice(0, MEDIA_DOWNLOAD_FILENAME_MAX - 3).replace(/[.\s_]+$/g, "") || "download";
+  }
+  if (!sanitized.toLowerCase().endsWith(".ts")) sanitized += ".ts";
+  return sanitized;
+}
+
+export function buildMediaDownloadFilename(options: {
+  channelName: string;
+  sourceLabel?: string;
+  programTitle?: string;
+  start?: Date;
+  end?: Date;
+}): string {
+  const parts = [options.channelName, options.sourceLabel, options.programTitle].filter((part): part is string =>
+    Boolean(part?.trim()),
+  );
+  if (options.start && options.end) {
+    parts.push(`${formatMediaDownloadTimestamp(options.start)}_${formatMediaDownloadTimestamp(options.end)}`);
+  }
+  return sanitizeMediaDownloadFilename(parts.join("_"));
+}
+
+function appendQueryParam(url: string, key: string, value: string): string {
+  const hashIndex = url.indexOf("#");
+  const hash = hashIndex === -1 ? "" : url.slice(hashIndex);
+  const withoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+  const encodedKey = `${encodeURIComponent(key)}=`;
+  if (withoutHash.includes(`?${encodedKey}`) || withoutHash.includes(`&${encodedKey}`)) return url;
+  const separator = withoutHash.includes("?") ? "&" : "?";
+  return `${withoutHash}${separator}${encodedKey}${encodeURIComponent(value)}${hash}`;
+}
+
+function withDownloadFilename(url: string, filename: string): string {
+  return appendQueryParam(url, "r2h-filename", filename);
+}
+
 export function pickChannelSource(channel: Channel, preferredIndex?: number): Source | undefined {
   const index = preferredIndex ?? getLastSourceIndex(channel.id);
   return channel.sources[index] ?? channel.sources[0];
@@ -93,12 +155,15 @@ export function pickCatchupSource(channel: Channel, preferredIndex?: number): So
 export function getChannelLiveMediaUrl(channel: Channel, preferredIndex?: number): string | null {
   const source = pickChannelSource(channel, preferredIndex);
   if (!source?.url) return null;
-  return toAbsoluteMediaUrl(source.url);
+  return withDownloadFilename(
+    toAbsoluteMediaUrl(source.url),
+    buildMediaDownloadFilename({ channelName: channel.name, sourceLabel: source.label }),
+  );
 }
 
 export function getProgramMediaUrl(
   channel: Channel,
-  program: CatchupProgramBound,
+  program: CatchupProgramBound & { title?: string },
   preferredIndex?: number,
   now = new Date(),
 ): string | null {
@@ -112,10 +177,30 @@ export function getProgramMediaUrl(
       ...catchupSource,
       url: stripPlaylistUrlLabel(catchupSource.url),
     };
-    return toAbsoluteMediaUrl(buildCatchupUrl(sourceForCopy, start, end, now));
+    return withDownloadFilename(
+      toAbsoluteMediaUrl(buildCatchupUrl(sourceForCopy, start, end, now)),
+      buildMediaDownloadFilename({
+        channelName: channel.name,
+        sourceLabel: catchupSource.label,
+        programTitle: program.title,
+        start,
+        end,
+      }),
+    );
   }
   if (program.start.getTime() <= now.getTime() && program.end.getTime() > now.getTime()) {
-    return getChannelLiveMediaUrl(channel, preferredIndex);
+    const source = pickChannelSource(channel, preferredIndex);
+    if (!source?.url) return null;
+    return withDownloadFilename(
+      toAbsoluteMediaUrl(source.url),
+      buildMediaDownloadFilename({
+        channelName: channel.name,
+        sourceLabel: source.label,
+        programTitle: program.title,
+        start: program.start,
+        end: program.end,
+      }),
+    );
   }
   return null;
 }

From 032d84d680359550ca8d6414f5cdea76ce0b41a6 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 2 Sep 2026 10:39:11 +0000
Subject: [PATCH 7/8] fix(http): NUL-terminate download names before .ts suffix
 check

strcasecmp() was reading past the sanitized filename, so names that
already ended in .ts could pick up a second suffix.

Co-authored-by: Stackie Jia <jsq2627@gmail.com>
---
 e2e/test_multicast.py | 3 ++-
 src/http.c            | 4 +++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/e2e/test_multicast.py b/e2e/test_multicast.py
index 1ab8b110..8cf617be 100644
--- a/e2e/test_multicast.py
+++ b/e2e/test_multicast.py
@@ -321,9 +321,10 @@ def test_head_rtp_sanitizes_filename_header_injection(self, r2h_binary):
             assert status == 200
             assert body == b""
             disposition = get_header(hdrs, "Content-Disposition")
-            assert "Set-Cookie" not in disposition
+            assert get_header(hdrs, "Set-Cookie") == ""
             assert "\r" not in disposition
             assert "\n" not in disposition
+            assert disposition.startswith("attachment;")
             assert 'filename="foo_Set-Cookie_ evil.ts"' in disposition
         finally:
             r2h.stop()
diff --git a/src/http.c b/src/http.c
index 0cbd7f56..f8a76f53 100644
--- a/src/http.c
+++ b/src/http.c
@@ -226,14 +226,16 @@ int http_sanitize_download_filename(const char *input, char *output, size_t outp
   if (out_len == 0)
     return -1;
 
+  tmp[out_len] = '\0';
+
   if (!http_filename_has_ts_suffix(tmp, out_len)) {
     if (out_len + 3 >= sizeof(tmp))
       out_len = HTTP_DOWNLOAD_FILENAME_MAX - 3;
     tmp[out_len++] = '.';
     tmp[out_len++] = 't';
     tmp[out_len++] = 's';
+    tmp[out_len] = '\0';
   }
-  tmp[out_len] = '\0';
 
   name_len = strlen(tmp);
   if (name_len + 1 > output_size)

From 967ac4e2bff818a95c98876abf0eedd69a61348e Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 2 Sep 2026 10:55:10 +0000
Subject: [PATCH 8/8] fix(web-player): use a light toast surface in simple
 appearance

Simple theme was reusing the video overlay background, which is always
slate-900. Give toasts their own semantic surface so light+simple stays
light while dark+simple and fancy are unchanged.

Co-authored-by: Stackie Jia <jsq2627@gmail.com>
---
 web-ui/src/components/player/player-toast.tsx |  4 ++--
 web-ui/src/index.css                          | 22 +++++++++++++++++++
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/web-ui/src/components/player/player-toast.tsx b/web-ui/src/components/player/player-toast.tsx
index 8fc55c77..530fad7d 100644
--- a/web-ui/src/components/player/player-toast.tsx
+++ b/web-ui/src/components/player/player-toast.tsx
@@ -42,10 +42,10 @@ export function PlayerToast({ toast }: { toast: PlayerToastState | null }) {
     >
       <div
         className={clsx(
-          "player-performance-overlay-background player-performance-effect flex max-w-[min(24rem,calc(100vw-2rem))] items-center gap-2 rounded-2xl border px-3.5 py-2.5 text-sm font-medium shadow-[0_16px_40px_-18px_rgba(15,23,42,0.55)] backdrop-blur-xl",
+          "player-performance-toast-background player-performance-effect flex max-w-[min(24rem,calc(100vw-2rem))] items-center gap-2 rounded-2xl border px-3.5 py-2.5 text-sm font-medium shadow-[0_16px_40px_-18px_rgba(15,23,42,0.55)] backdrop-blur-xl",
           isSuccess
             ? "border-blue-300/40 bg-[linear-gradient(145deg,rgba(239,246,255,0.94),rgba(238,242,255,0.9))] text-blue-800 dark:border-blue-300/20 dark:bg-[linear-gradient(145deg,rgba(15,32,64,0.94),rgba(30,27,75,0.9))] dark:text-blue-100"
-            : "border-rose-300/40 bg-[linear-gradient(145deg,rgba(255,241,242,0.94),rgba(255,228,230,0.9))] text-rose-800 dark:border-rose-300/20 dark:bg-[linear-gradient(145deg,rgba(64,15,32,0.94),rgba(75,27,45,0.9))] dark:text-rose-100",
+            : "player-performance-toast-error border-rose-300/40 bg-[linear-gradient(145deg,rgba(255,241,242,0.94),rgba(255,228,230,0.9))] text-rose-800 dark:border-rose-300/20 dark:bg-[linear-gradient(145deg,rgba(64,15,32,0.94),rgba(75,27,45,0.9))] dark:text-rose-100",
         )}
       >
         <Icon className="h-4 w-4 shrink-0" />
diff --git a/web-ui/src/index.css b/web-ui/src/index.css
index 37c0b33d..207e7fef 100644
--- a/web-ui/src/index.css
+++ b/web-ui/src/index.css
@@ -142,6 +142,7 @@ html.player-theme-simple
     .player-performance-page-background,
     .player-performance-panel-background,
     .player-performance-overlay-background,
+    .player-performance-toast-background,
     .player-performance-warning-background,
     .player-performance-error-background,
     .player-performance-controls-background,
@@ -215,6 +216,27 @@ html.player-theme-simple .player-performance-overlay-background {
   border-color: #475569;
 }
 
+html.player-theme-simple .player-performance-toast-background {
+  background-color: #eff6ff;
+  background-image: none;
+  border-color: #93c5fd;
+}
+
+html.player-theme-simple .player-performance-toast-background.player-performance-toast-error {
+  background-color: #fff1f2;
+  border-color: #fda4af;
+}
+
+html.dark.player-theme-simple .player-performance-toast-background {
+  background-color: #0f2040;
+  border-color: #1e3a8a;
+}
+
+html.dark.player-theme-simple .player-performance-toast-background.player-performance-toast-error {
+  background-color: #401020;
+  border-color: #9f1239;
+}
+
 html.player-theme-simple .player-performance-warning-background {
   border-color: #854d0e;
   background-color: #2b2111;