TV Time Backup Extractor

Recover readable TV Time titles, favorites, cached episodes, watch events, and media references from an authorized encrypted local iPhone or iPad backup. The extractor reads the completed backup, copies only matching TV Time app-domain files into a fresh private destination, and produces human-readable reports plus detailed CSV tables.

The project is free and open source. iMazing is not required. It does not modify the phone or source backup, contact TV Time, restore data to the app, or provide an official cloud-account export.

Release status: v0.2.0 remains the latest stable release. The v0.3.1-alpha.1 candidate adds a downloadable Windows x64 tester build alongside updated Mac and Python packages. It is not published yet. Windows, Android, and official-export recovery remain experimental.

The v0.3.1-alpha.1 release record lists the required evidence and remaining device-specific limits.

This project is independent and is not affiliated with or endorsed by TV Time or Apple. TV Time and related marks belong to their respective owners. Use it only with data you own or are authorized to access, and comply with applicable law and service terms.

Choose a route

Route	Best for	Requirements
Native macOS app	Most Mac users	macOS 14 or later and the v0.2.0 DMG matching the Mac's architecture
Python CLI recovery	macOS, Linux, automation, and development	An explicitly selected Python 3.10 through 3.13 plus the pinned dependencies
Windows alpha app	Encrypted iOS, local Android, and export recovery testing	Windows x64, BitLocker or device encryption, and the signed alpha tester bundle
Android/export recovery	Mac, Windows, or CLI users with an already-preserved source	Supported legacy backup, allowlisted snapshot, or official ZIP/CSV export

The published native app is the normal Mac installation:

• Apple silicon Macs use the Apple-Silicon-arm64 DMG;
• Intel Macs use the Intel-x86_64 DMG; and
• end users need no Python, iMazing, Homebrew, Git, GitHub CLI, or Apple developer tools.

Download it from the official v0.2.0 release. See the macOS guide for installation and the v0.2.0 release record for the completed distribution gates.

What recovery needs

Every route needs an owner-controlled local source, private local output storage, and enough free space for processing and reports.

Encrypted iOS or iPadOS recovery also needs a completed encrypted local backup made with Finder, Apple Devices, or iTunes, its encryption password, and the phone safely ejected and disconnected after backup completion is confirmed. Recovery does not duplicate the whole device backup.

Android and official-export routes use their own selected local source. They do not require an iOS backup or its password.

Rooting a phone, bypassing Android backup policy, cloud-account scraping, and restoring recovered data to TV Time are not supported. Modern Android release apps commonly disable legacy backup; the tool reports that limitation rather than bypassing it.

Native macOS app workflow

The published app supports macOS 14 or later:

1. Download the DMG for Apple silicon or Intel from the project's release page and verify its published checksum.
2. Open the DMG, drag TV Time Backup Extractor to Applications, eject the DMG, and open the app from Applications.
3. Choose the Apple backup folder. If it contains one completed backup, the app selects it automatically. If several backups appear, open the intended one before choosing it.
4. The app creates a fresh recovery folder in private app-managed local storage. There is no destination picker, mounted disk-image requirement, or hard-coded user path.
5. Review the read-only preflight: encryption state, finished snapshot state, backup date and size, manifest size, local free space, and minimum working space.
6. Enter the backup password in the secure field and acknowledge that recovered reports are readable plaintext on this Mac. FileVault remains recommended for whole-disk protection.
7. Start recovery and keep the Mac awake until the result screen appears.
8. Validate the aggregate chart and counts, then open the private visual, PDF, or Markdown report, or reveal the app-managed recovery folder in Finder.

Use Show Previous Recoveries on the first screen to find older completed or incomplete runs. Review them before deleting anything; the app never silently removes recovery output.

The password is passed only to the bundled local helper and is not intentionally written to disk. The app clears its field after starting, but neither Swift nor Python can guarantee immediate erasure of every in-memory copy.

Cancelling the backup check creates no recovery output. Cancelling an active recovery, closing its window, or quitting the app requires confirmation. A confirmed cancellation preserves incomplete output for diagnosis; it never reuses or silently deletes that output. Every retry gets a fresh destination.

The completed native result screen provides:

• a verified-package panel confirming selected source stability, completion-marker consistency, copied-file integrity, and sealed report artifacts;
• an aggregate bar chart and explicit watched/saved movie and named/unnamed event counts;
• copied-file and byte-count-difference summaries;
• aggregate image, trailer, and media-URL reference counts;
• a visual report, print-friendly PDF, and complete Markdown catalogue, with a clear explanation when the optional PDF is omitted; and
• guarded actions to open reports or reveal the analysis directory.

Opening a report uses the default browser or document viewer. Its private filename may then appear in that application's history or macOS Recent Items. See Privacy and safe handling.

Reports and tables

A successful full recovery creates these primary reports under TVTime-Extraction/analysis/:

• TVTime-Recovered-Data.md: canonical readable text listing every recovered record and each available name
• TVTime-Recovered-Data.html: accessible, self-contained primary visual report with charts and semantic tables; it works offline, contains no script, and does not request remote media
• TVTime-Recovered-Data.pdf: optional print-friendly companion generated from the same report model; use the HTML report for tagged semantic structure with assistive technology
• Suite-TV-Liberator-confirmed.zip: Suite TV import containing only exact recovered watch state
• Suite-TV-Liberator-estimated-progress.zip: alternate Suite TV import that fills missing per-episode state up to recovered aggregate series counts

Markdown, HTML, and PDF are rendered from one shared safe display model, including identical missing-title placeholders and a copy-size-differences section when backup metadata and copied byte counts disagree. Detailed CSV tables remain the exact archive; the readable formats replace control characters with spaces, trim surrounding whitespace, and collapse whitespace runs while preserving the remaining recovered Unicode text.

The PDF is deliberately omitted when the available embedded font or shaping support cannot faithfully render every recovered character. This is a fidelity safeguard, not a failed recovery: the Markdown and offline HTML remain complete. Normalized CSV tables preserve the detailed private data used by the reports, including titles, favorites, episodes, and exact watch events.

For Suite TV, prefer Suite-TV-Liberator-confirmed.zip when exactness matters. The estimated archive preserves every exact recovered watch and never estimates specials, but fills the oldest remaining regular episodes until each recovered aggregate watched count is reached. It cannot reconstruct which skipped, out-of-order, or repeatedly watched episodes produced that count. Both archives use the five-file TV Time Liberator layout and are created entirely offline; movies without a recovered positive TVDB identifier are omitted because Suite TV cannot identify them safely.

Successful full recovery has two versioned machine-readable checkpoints:

• metadata/run_state.json has status set to complete after selected-file extraction finishes and the source is revalidated; and
• analysis/recovery_state.json has status set to complete in the atomically promoted report directory and binds the exact report/table artifact set, aggregate counts, byte sizes, and SHA-256 digests.

Do not treat an output as a completed full recovery if either expected marker is absent or not complete. Standalone extract intentionally creates only the extraction marker. Never edit a marker or merge files from separate runs. See the complete output reference.

Free-space model

The extractor does not duplicate the complete iPhone or iPad backup.

The initial manifest-processing preflight checks for at least the larger of:

• 512 MiB; or
• twice the source Manifest.db size.

This initial floor is enough to begin safe manifest processing; it is not the full recovery-space requirement. After the encrypted manifest identifies the TV Time domains, recovery requires the sum of the selected files' declared sizes, the largest selected encrypted source payload as a staging snapshot, headroom equal to the larger of 64 MiB or 10% of selected declared bytes, and one retained Manifest.db only when the advanced decrypted-manifest option is enabled. The post-retention check omits that already-retained manifest allowance but still includes the largest staging snapshot.

The full backup size shown in preflight is useful provenance; it is not the required destination size. Keep extra headroom for filesystem allocation and future retries, and do not unmount the destination while recovery is active.

Python CLI fallback

The CLI is free and supports Python 3.10 through 3.13. The private candidate adds native Win32 handle binding for encrypted iOS source files and fresh output; use its WinUI package for the strongest Windows containment. It also adds recover-android-backup, recover-android-snapshot, recover-export, android-probe, and the explicitly acknowledged android-capture command.

Install from a source checkout or ZIP

Download the repository as a source ZIP, or clone it if Git is already available. Git is optional. From the project directory on macOS or Linux:

python3.13 -m venv .venv
./.venv/bin/python -m pip install --require-hashes --only-binary=:all: --requirement requirements.lock
./.venv/bin/python -m pip install --require-hashes --only-binary=:all: --requirement requirements-source-build.lock
./.venv/bin/python -m pip install --no-index --no-build-isolation --no-deps .
./.venv/bin/python -m pip check
./.venv/bin/python -m tvtime_extractor --version

On Windows PowerShell:

py -3.13 -m venv .venv
.venv\Scripts\python.exe -m pip install --require-hashes --only-binary=:all: --requirement requirements.lock
.venv\Scripts\python.exe -m pip install --require-hashes --only-binary=:all: --requirement requirements-source-build.lock
.venv\Scripts\python.exe -m pip install --no-index --no-build-isolation --no-deps .
.venv\Scripts\python.exe -m pip check
.venv\Scripts\python.exe -m tvtime_extractor --version

The dependency versions and downloadable artifacts are pinned. requirements.lock contains hashes for supported macOS, Windows, and Linux wheels; installation rejects an unlisted artifact and never builds a dependency from source. The minimal source-build backend is separately hash-locked, and the final local-project install disables build isolation and the package index so it cannot fetch an undeclared build tool. Virtual environments are not portable between folders or computers; create a new one if the project moves.

Run a full recovery

Use an individual backup folder and a destination run path that does not yet exist. The immediate encrypted output parent must already exist; the fresh run child itself must not exist. This parent-exists/child-does-not rule also applies on Windows. Public v0.2.0 still has no Windows recovery app; the private candidate uses the native package documented below. On macOS or Linux:

./.venv/bin/python -m tvtime_extractor recover \
  --backup "/path/to/DEVICE_BACKUP" \
  --output "/path/to/PRIVATE_NEW_RUN" \
  --acknowledge-sensitive-output

The CLI completes and visibly summarizes the full read-only backup/destination preflight before the hidden password prompt appears. It consumes the same source-identity receipt after the prompt, then holds the selected parent and fresh output-root directory identities through recovery. A replaced backup root, changed bound critical metadata, or changed displayed source aggregate fails before output creation; selected payload files are snapshot-verified during extraction and revalidated before extraction completion. POSIX descendants remain relative to the descriptor-rooted working directory. Standalone analyze and report hold and revalidate the exact existing extraction root; on Windows they use a non-delete-sharing handle and reject reparse points. Do not place the password in the command, environment, shell history, or a support request. The default terminal output is a concise readable summary; --json is an explicit private automation option and is not the default.

For the unpublished private Windows candidate, build and install the local MSIX as documented in the Windows guide. Nothing in that workflow uploads or publishes the package. Its direct and transitive WinUI dependencies are committed in locked mode; a floating NuGet restore is rejected. Encrypted iOS recovery in that candidate requires Windows 11 x64 and remains blocked from release-ready status until a synthetic Windows build, screenshot, and end-to-end smoke test confirm the native flow.

Linux accepts only a conservative set of ordinary local filesystem types. FUSE, network, shared, virtual-machine shared-folder, temporary, overlay, and unknown filesystem types are refused with no override.

All recovery sources must be owner-controlled and local. Known cloud-sync/shared paths, nonlocal volumes, symbolic links, Windows reparse points, and cloud-hydrated placeholders are rejected before source inspection. On Windows, the source must also be on private local NTFS storage so file identity checks remain trustworthy; copy an owner-controlled source there before recovery.

The encrypted-iOS and core processing commands are:

• recover: preflight, extract, analyze, and report in one workflow
• extract: copy and inventory matching TV Time app-domain files only
• analyze: build normalized private tables from one complete extraction
• report: build readable and visual reports from one complete analysis

The experimental Android and official-export commands are:

• recover-android-backup: recover a compatible legacy Android backup container
• recover-android-snapshot: recover an already-preserved Android database snapshot
• recover-export: recover a supported official TV Time ZIP or CSV export
• android-probe: report privacy-safe legacy backup capability
• android-capture: explicitly capture a supported legacy Android backup

Run python -m tvtime_extractor <command> --help through the virtual environment for exact options. --debug deliberately retains chained third-party exceptions and can expose backup paths, dependency details, recovered names, or password text. Use it only in a private local terminal and never paste or share its traceback. The advanced extract --include-decrypted-manifest and analyze --include-raw-cache switches retain substantially more account or device data and are off by default. They are deliberately not available on the sealed recover workflow: preserve those advanced outputs for private manual analysis, and use a fresh default recovery when native completion validation is required.

Extraction boundary and limitations

The extractor opens the completed backup read-only and temporarily decrypts its file index inside the private output. It requires the primary TV Time domain AppDomain-com.tozelabs.tvshowtime and includes directly related TV Time plugin domains. Every selected regular file is copied below TVTime-Extraction/raw/ with its domain and manifest-relative path preserved. File counts, sizes, and hashes are recorded privately before analysis.

The primary parser reads the copied Documents/DioCache.db and also recognizes supported legacy extensionless URL-cache archives in that same directory. Those old NSKeyedArchiver responses are decoded entirely offline; the extractor never replays their private request URLs. An available image-cache database is catalogued as a bonus. Local caches can be incomplete, events can survive without names, and TV Time can change its schema. Missing data is stated rather than guessed. Retain the original encrypted backup until titles, favorites, episodes, watch events, and completion markers have been validated.

Read before using real data

• macOS guide
• Windows guide
• Refract series conversion guide
• Private synthetic cross-platform checks
• Linux guide
• Privacy and safe handling
• Output reference
• Troubleshooting
• Support policy
• Security policy

Automated tests use invented fixtures only. The repository must never contain a real backup, database, device manifest, recovered report, stable account or device identifier, private URL, password, or viewing history.

License

Licensed under the MIT License. See CONTRIBUTING.md and CHANGELOG.md. The software is provided without warranty and is not a backup-restoration tool. A packaged macOS app also carries its complete third-party texts and an exact component/license inventory under Contents/Resources/Licenses.