Remove from TVHeadend

Once an episode is in your library, you no longer need the copy in TVHeadend's recordings folder. Freetvarr can remove it after Plex has the file. This is optional, and you turn it on per series.

How it works

Freetvarr deletes the recording file and keeps TVHeadend's entry for it. That entry is how TVHeadend knows the episode is already recorded. Before a series recording records a repeat, TVHeadend's duplicate check looks for an earlier entry with the same episode. If the entry is gone, TVHeadend records the repeat, and the next sync imports the same episode again.

For each recording, Freetvarr makes these calls to TVHeadend's DVR API, in this order:

1. idnode/delete on any re-record TVHeadend has scheduled for the recording (Re-records).
2. idnode/save sets the entry's DVR log retention to Forever. The entry otherwise takes the DVR profile's Recording info retention period, which defaults to On file removal and drops the entry as soon as the file goes.
3. dvr/entry/prevrec/set marks the entry as previously recorded. The mark survives a TVHeadend restart and stops TVHeadend from re-recording the entry.
4. dvr/entry/remove deletes the file. The entry moves to TVHeadend's Removed Recordings tab.

These calls go straight to TVHeadend on your home network, with no cloud service involved.

Re-records

A TVHeadend DVR profile can re-record a recording that has too many data errors. TVHeadend then schedules the next broadcast of the same episode as a child entry of the first recording. Freetvarr still imports the first recording and shows the errors as a warning on the Recorded step. Once that import succeeds, the re-record is unwanted, so Freetvarr deletes the child entry before it removes the parent. On TVHeadend 4.3-2794~g5ce3ff63c, a parent removed while its re-record was still scheduled was followed by a TVHeadend crash. Deleting the child first avoids that state.

Duplicate detection

Freetvarr's series recordings use the TVHeadend Record if different episode number setting. The kept entries let that setting skip a repeat of an imported episode. The setting needs an episode number on both sides. A repeat that the TV guide lists without one still records, and Freetvarr imports it again.

To let TVHeadend record an episode again, delete its entry in the Removed Recordings tab of TVHeadend's web interface. The entries hold no video, so they use almost no disk space.

Turn it on

Remove after import is a per-series switch on the SERIES tab. Press EDIT on a series, turn on REMOVE FROM TVHEADEND AFTER IMPORT, then press SAVE. Turn it on for series you are happy to keep only in your library. Leave it off for anything you want a second copy of.

When it removes

Freetvarr removes a recording only after Plex confirms the imported file, and only when both of these checks pass:

• The Plex guard. If Freetvarr tried the Plex refresh and it failed, Freetvarr skips the remove and the recording stays in TVHeadend. To turn this off, switch off Wait for Plex before removing recordings from TVHeadend in SETTINGS → PLEX.
• The cut guard. For a CUT-mode show, the TVHeadend copy is the last untouched original once Freetvarr has rewritten the local file. The remove waits for the cut to pass its checks. A failed cut keeps the original (Ad removal).

Removed recordings stay in Recordings, marked NOT IN TVHEADEND, for 30 days.

If a remove fails

• "Recording not in TVHeadend's finished list" means the entry has left TVHeadend's Finished Recordings tab, usually because you removed or deleted it in TVHeadend's own web interface. Nothing needs fixing (the row stays as it is).
• An HTTP 401 or 403 means the Freetvarr user lacks DVR rights. In TVHeadend's web interface, tick Video recorder Basic and Manage all under Configuration → Users → Access Entries (Manage all covers recordings another user scheduled). See TVHeadend.
• A file that won't disappear is a permissions problem, not an API one. TVHeadend deletes the file as its own user, so check that PUID/PGID in the .env match across both Docker containers.