Skip to content

Merge Detection & Data Recovery

When scenes are merged in Stash, Peek automatically detects this and preserves your user activity data like watch history, ratings, and favorites.

How Scene Merging Works in Stash

In Stash, you can merge duplicate scenes together. This is useful when:

  • You download a higher resolution version of a scene you already had
  • You discover duplicates after adding new content
  • You have alternate versions (director's cut, different endings)

When merging in Stash, the source scene is completely deleted - all its file fingerprints are transferred to the destination scene, but the source scene ID no longer exists.

The Problem Peek Solves

Without merge detection, when Peek syncs with Stash:

  1. Peek sees the source scene is missing from Stash
  2. Peek soft-deletes the source scene
  3. Your watch history, ratings, and favorites become "orphaned"
  4. When you view the merged (destination) scene, your activity data is missing

With merge detection, Peek automatically transfers your activity to the surviving scene.

Automatic Merge Detection

How It Works

Peek uses PHASH (perceptual hash) fingerprints to detect merges:

  1. During sync, Peek soft-deletes every scene that is gone from Stash
  2. For each of those scenes with a PHASH and some user activity, Peek looks for live scenes with the same PHASH on the same Stash instance. With several Stash servers, a scene is never merged into a scene of another server, even when both hold the same file
  3. When exactly one such scene exists, Peek transfers all user activity to it
  4. When several exist, Peek does not guess: the scene waits in the Merge Recovery tab for an admin to pick the target
  5. Scenes deleted in the same sync are never targets: they are already soft-deleted when Peek looks for matches, so two duplicates removed together cannot swap your activity back and forth

If a sync stops between the soft-delete and the transfer, the next sync picks up the scenes soft-deleted in the last 24 hours that still have activity and no merge record.

What Gets Transferred

For each user with activity on the merged scene (watch history, a rating or favorite, or the scene in one of their playlists):

Data Type Transfer Logic
Play count Added together
Play duration Added together
O count Added together
Resume time Target scene's value kept (if any)
Last played Most recent timestamp kept
Rating Target scene's rating kept (if set)
Favorite OR logic - if either was favorited, result is favorited
Playlist entries Point to the target scene (dropped where the playlist already has it)

Automatic and Seamless

You don't need to do anything - merge detection happens automatically during normal syncs.

Admin Recovery Tool

For scenes that were merged before this feature was implemented, or where automatic detection found no match or several, admins can manually recover orphaned data. The tool also lists deleted scenes that are only in someone's playlist (no history, no rating), so those entries can be merged into the re-scanned file too.

Accessing the Tool

  1. Go to Settings (gear icon)
  2. Switch to Server Settings
  3. Open the Merge Recovery tab

Understanding the Interface

The Merge Recovery tab shows:

  • Total orphaned scenes that someone's play history, rating or playlist still points at
  • For each orphan:
    • Scene title, the Stash instance it was on, and when it was deleted
    • PHASH value (if available)
    • Activity summary: total plays, ratings, favorites, and how many playlist entries hold the scene
    • Potential PHASH matches, all on the orphan's instance

Recovering Orphaned Data

For a single scene:

  1. Click on an orphaned scene to expand it
  2. Review the potential matches. Every match has the same PHASH as the orphan. The one most recently updated in Stash comes first and is marked Recommended
  3. Either:
    • Click Transfer next to a match to transfer activity to that scene
    • Enter a scene ID manually if you know the correct target. The ID is a scene on the orphan's instance (the field says which); a scene that is deleted or unknown there is refused
  4. The activity data is transferred and an audit record is created

For all scenes at once:

  1. Click Auto-Reconcile All
  2. Peek transfers activity for every orphan with exactly one PHASH match on its instance
  3. Orphans with no match or with several are skipped (handle them one by one)

Discarding Orphaned Data

If an orphaned scene's data is no longer relevant (e.g., you deleted the scene intentionally):

  1. Expand the orphan
  2. Click Discard Activity
  3. Confirm the action

This also removes the scene from every playlist that holds it. Only that scene's activity on its own instance is deleted; a scene with the same ID on another Stash instance keeps its data.

Permanent Action

Discarding orphaned data permanently deletes the watch history, the ratings and the playlist entries. This cannot be undone.

Limitations

When Automatic Detection Fails

PHASH-based detection may not work when:

  • Scene had no PHASH - Fingerprinting wasn't run in Stash before the scene was synced to Peek
  • Scene was deleted before PHASH sync - Peek didn't have the PHASH stored
  • Scene was split, not merged - Different operation, same result in Peek

In these cases, use the admin recovery tool to manually reconcile.

PHASH Not Available

If a scene shows "No PHASH" in the recovery tool:

  1. The scene was synced before fingerprint syncing was implemented
  2. You can manually enter the target scene ID if you know it
  3. Future syncs will include PHASH data for new scenes

Audit Trail

Every merge reconciliation (automatic or manual) creates an audit record containing:

  • Source and target scene IDs, and the Stash instance of each
  • Which PHASH matched them (if automatic)
  • All transferred data values
  • When the reconciliation happened
  • Who performed it (system for automatic, admin username for manual)

This ensures full traceability of data transfers.

Best Practices

Before Merging in Stash

  1. Run a full sync in Peek first to ensure PHASHes are stored
  2. Merge scenes in Stash as normal
  3. Run another sync - merge detection happens automatically

Checking Results

After a sync where merges occurred:

  1. Check the sync log for "Detected merge" messages
  2. Verify your watch history appears on the destination scene
  3. If something is missing, check the admin recovery tool

For Admins

  • Periodically check the Merge Recovery tab for orphaned scenes
  • Use Auto-Reconcile All to quickly process orphans with one match
  • Manually review and reconcile scenes with several matches or none

Troubleshooting

Activity Not Transferred

Possible causes:

  • PHASH wasn't available at sync time
  • Multiple potential matches exist on the scene's instance (check admin tool)
  • Scene was deleted, not merged

Solution: Use the admin recovery tool to manually reconcile.

Wrong Scene Got the Activity

If activity was transferred to the wrong scene:

  1. Currently, there's no automatic undo
  2. Contact your admin to manually adjust records if needed
  3. Future enhancement: undo capability using audit records

Orphaned Scenes Keep Appearing

If the same scenes keep showing as orphaned:

  • They may have been deleted in Stash (not merged)
  • Check if they should be discarded rather than reconciled
  • If they're legitimately orphaned, use the recovery tool

Next Steps