House MD Teardrop Intro Restoration (Landmark Audio Sync)

This tool replaces the international House MD intro, present in current public releases of House, with the audio of the original Teardrop Intro sequence. The replacement is acccomplished by aligning a Teardrop landmark (piano chord) to the audio from the international intro. Specifically, it relies on two landmark transients from the two international intros which are detected in each episode, or leaves the episode as-is if Teardrop is already present.

This is intended for personal usage only; it is the user's responsibility to acquire the source files. The output of this utility is not intended for public distribution.

Requirements

• Python 3.11+
• uv
• ffmpeg and ffprobe available on PATH

Install

uv sync
uv run house-teardrop --help

Assets

• This repository does not include episode files, reference audio, or any copyrighted soundtrack assets.
• The data/ directory is intentionally gitignored; supply your own source episodes and reference files locally.
• config/no_intro_skip_episodes.json is the default skip-list file used by the batch pipeline.

Commands

# 1) Batch run (recursive source scan, mirrored output tree)
uv run house-teardrop run \
  --input-root /path/to/house_source \
  --output-root /path/to/house_output \
  --teardrop-audio /path/to/teardrop.flac \
  --reference-landmarks-json data/intl-intro/reference_landmarks.json \
  --confidence-min 0.55 \
  --peak-ratio-min 1.3 \
  --no-intro-skip-json config/no_intro_skip_episodes.json \
  --existing-teardrop-confidence-min 0.85 \
  --existing-teardrop-confidence-margin 0.20 \
  --manifest-file sync_manifest.json \
  -j 4

# Optional: restrict candidates to specific references
uv run house-teardrop run \
  --input-root /path/to/house_source \
  --output-root /path/to/house_output \
  --teardrop-audio /path/to/teardrop.flac \
  --reference-audio data/intl-intro/intl_house-md.mp3 \
  --reference-audio data/intl-intro/intl_house-md_type2.mp3

# Optional verification clip
uv run house-teardrop verify \
  --episode /path/to/output_episode.mkv \
  --sync-time 188.458 \
  --output-clip /path/to/preview.mp4

Behavior

• Recursive input discovery under --input-root
• Output path mirrors source tree under --output-root
• Chapter markers are used only to narrow search windows
• Landmark-based audio matching determines final placement timing
• Replacement requires both confidence and isolated-peak checks to pass
• Existing Teardrop intros are detected and skipped automatically
• Optional chapter-missing/outlier fallback scan (60s..600s)
• Known no-intro episodes are blocked via skip list safety net
• No-intro episodes are copied through unchanged and marked no_intro in manifest
• Batch run always continues and prints summary
• Video/subtitles are stream-copied
• Audio preserved as stereo or 5.1; Teardrop injected into front L/R

Architecture

• detection: loads reference profiles, decodes audio windows, extracts landmark features, and scores candidate intro matches
• media: probes media metadata, builds ffmpeg filtergraphs, and performs the intro-audio replacement
• pipeline: builds batch work items, processes one episode through explicit phases, and persists manifest results

Development

uv run python -m unittest discover -s tests -q

Generated files such as sync_manifest.json are intended to stay local and are gitignored.

Reference Landmark JSON

Default path: data/intl-intro/reference_landmarks.json

{
  "intl_type1": {
    "path": "intl_house-md.mp3",
    "landmark_seconds": 6.64,
    "role": "production"
  },
  "intl_type2": {
    "path": "intl_house-md_type2.mp3",
    "landmark_seconds": 6.23,
    "role": "production"
  },
  "s01e02_diag": {
    "path": "s01e02_intro_ref_10s.wav",
    "landmark_seconds": 6.23,
    "role": "diagnostic"
  }
}

• role=diagnostic entries are ignored unless --include-diagnostic-references is set.

No-Intro Skip List

Default path: config/no_intro_skip_episodes.json

{
  "skip_episodes": ["S01E01", "S08E22"]
}

Manifest

sync_manifest.json stores one record per episode with fields including:

• status: processed|no_intro|failed|skipped_existing
• reason
• source_path, output_path
• chapter_end_time, search_window
• confidence, detection_method
• matched_reference_key, matched_reference_audio, reference_confidences
• teardrop_confidence, teardrop_peak_ratio, teardrop_confidence_margin
• detected_start_time, detected_transient_time
• audio_start_time, intro_end_time
• placement_mode, teardrop_landmark_seconds, applied_alignment_shift
• has_intro

License

Code in this repository is licensed under the MIT License. Media files, episode sources, and soundtrack assets are not included and remain subject to their own licenses and ownership restrictions.