Docs pass: update headers and READMEs for all new scripts
Script headers (6 files): - Add OPERATIONAL SAFEGUARDS section to all discovery + emby sync scripts - Add STATE FILES section to all 3 discovery scripts - Add CONFIGURATION section to emby_to_*_sync.sh - Rename USAGE → RUNTIME MODES in emby_to_*_sync.sh (doc standard) - Fix SONARR_DISCOVERY_MONITOR_MODE default doc: "future" → "all" Media/README-Media.md: - Remove "WIP prototype" label; describe all 3 discovery scripts - Add discovery scripts to scripts table and HOW THE SCRIPTS RELATE diagram - Add weekly discovery schedule block to EXECUTION ORDER section - Update intro to mention behavior-driven discovery Media/Manual-Media.md: - Add configuration reference sections for all 3 discovery scripts - Add flag reference sections for all 3 discovery scripts Tools/README-Tools.md: - Add "Library Sync Bootstrap" category and emby_to_*_sync.sh to scripts table - Add emby sync scripts to HOW THE SCRIPTS RELATE diagram Tools/Manual-Tools.md: - Update emby sync notes: search commands now fire immediately after add README.md: - Update Media folder description to include discovery - Update weekly schedule to show discovery scripts - Update README table entry for Media
This commit is contained in:
Gmer4Lfe
@@ -216,6 +216,64 @@ LIDARR_ART_SLEEP_BETWEEN=1 # seconds between fanart.tv API calls (rate li
|
||||
|
||||
---
|
||||
|
||||
### Lidarr Discovery
|
||||
|
||||
```bash
|
||||
LIDARR_DISCOVERY_THRESHOLD=70 # minimum score for Stage 1 seeds and Stage 2 adds
|
||||
LIDARR_DISCOVERY_LOOKBACK_DAYS=7 # Emby play history window in days
|
||||
LIDARR_DISCOVERY_MIN_PLAYS=3 # min plays before an artist is evaluated as a seed
|
||||
LIDARR_DISCOVERY_MAX_ADDS=5 # max seeds (Stage 1) and max adds (Stage 2) per run
|
||||
LIDARR_DISCOVERY_USER_CAP_PCT=35 # max % any one user contributes to play weight
|
||||
LIDARR_DISCOVERY_REJECT_COOLDOWN=30 # days before re-evaluating a Stage 2 reject
|
||||
LIDARR_DISCOVERY_HISTORY="$DATA_DIR/lidarr_discovery_history.db"
|
||||
```
|
||||
|
||||
Requires `HOST*_LASTFM_API_KEY` in `master_host*.conf`.
|
||||
|
||||
---
|
||||
|
||||
### Radarr Discovery
|
||||
|
||||
```bash
|
||||
RADARR_DISCOVERY_THRESHOLD=52 # minimum score to add a candidate
|
||||
RADARR_DISCOVERY_LOOKBACK_DAYS=30 # Emby watch history window in days
|
||||
RADARR_DISCOVERY_MAX_SEEDS=5 # max seed movies from Stage 1
|
||||
RADARR_DISCOVERY_MAX_ADDS=5 # max movies to add per run
|
||||
RADARR_DISCOVERY_MIN_VOTE_COUNT=100 # min TMDB votes for a candidate
|
||||
RADARR_DISCOVERY_MIN_RATING=60 # min TMDB vote_average × 10 (60 = 6.0/10)
|
||||
RADARR_DISCOVERY_REJECT_COOLDOWN=60 # days before re-evaluating a rejected movie
|
||||
RADARR_DISCOVERY_SEED_LIBRARIES=("Movies") # Emby libraries to draw seeds from
|
||||
RADARR_DISCOVERY_HISTORY="$DATA_DIR/radarr_discovery_history.db"
|
||||
```
|
||||
|
||||
Requires `HOST*_TMDB_API_KEY` in `master_host*.conf`.
|
||||
|
||||
---
|
||||
|
||||
### Sonarr Discovery
|
||||
|
||||
```bash
|
||||
SONARR_DISCOVERY_THRESHOLD=52 # minimum score to add a candidate
|
||||
SONARR_DISCOVERY_LOOKBACK_DAYS=14 # Emby episode history window in days
|
||||
SONARR_DISCOVERY_MAX_SEEDS=5 # max seed series from Stage 1
|
||||
SONARR_DISCOVERY_MAX_ADDS=3 # max shows to add per run (TV is a larger commitment)
|
||||
SONARR_DISCOVERY_MIN_VOTE_COUNT=50 # min TMDB votes for a candidate
|
||||
SONARR_DISCOVERY_MIN_RATING=65 # min TMDB vote_average × 10 (65 = 6.5/10)
|
||||
SONARR_DISCOVERY_REJECT_COOLDOWN=60 # days before re-evaluating a rejected show
|
||||
SONARR_DISCOVERY_USER_EPISODE_CAP=8 # max episodes per user in seed scoring
|
||||
SONARR_DISCOVERY_MONITOR_MODE="all" # "all" = all seasons monitored; "future" = upcoming only
|
||||
SONARR_DISCOVERY_HISTORY="$DATA_DIR/sonarr_discovery_history.db"
|
||||
# SONARR_EMBY_LIBRARIES is shared with emby_to_sonarr_sync — see Orchestrator Job Order
|
||||
```
|
||||
|
||||
Requires `HOST*_TMDB_API_KEY` in `master_host*.conf`.
|
||||
|
||||
> **MONITOR_MODE note:** Use `"all"` (default) to have Sonarr search all existing seasons
|
||||
> after adding a show. `"future"` only marks upcoming seasons as monitored — shows where
|
||||
> all seasons have already aired will appear unmonitored and Sonarr will not search for them.
|
||||
|
||||
---
|
||||
|
||||
### Orchestrator Job Order
|
||||
|
||||
```bash
|
||||
@@ -634,3 +692,59 @@ Show configuration and API key status.
|
||||
|
||||
`lidarr_missing_art.sh --log`
|
||||
Verbose per-album, per-artist output.
|
||||
|
||||
---
|
||||
|
||||
### playback_aware_lidarr_discovery.sh
|
||||
|
||||
`playback_aware_lidarr_discovery.sh`
|
||||
Score Emby play history, run Last.fm getSimilar on top artists, add candidates above
|
||||
threshold to Lidarr. Triggers ArtistSearch immediately after each successful add.
|
||||
|
||||
`playback_aware_lidarr_discovery.sh --dry-run`
|
||||
Score and rank all Stage 1 seeds and Stage 2 candidates. No Lidarr API calls. No writes
|
||||
to history file. Shows exactly what would be added and at what score.
|
||||
|
||||
`playback_aware_lidarr_discovery.sh --status`
|
||||
Show config values, history file path and size, and API key status.
|
||||
|
||||
`playback_aware_lidarr_discovery.sh --log`
|
||||
Verbose per-artist scoring output for both stages.
|
||||
|
||||
---
|
||||
|
||||
### playback_aware_radarr_discovery.sh
|
||||
|
||||
`playback_aware_radarr_discovery.sh`
|
||||
Score recently watched Emby movies, run TMDB recommendations on seeds, add candidates
|
||||
above threshold to Radarr. Triggers MoviesSearch immediately after each successful add.
|
||||
|
||||
`playback_aware_radarr_discovery.sh --dry-run`
|
||||
Score and rank all Stage 1 seeds and Stage 2 candidates. No Radarr API calls. No writes
|
||||
to history file.
|
||||
|
||||
`playback_aware_radarr_discovery.sh --status`
|
||||
Show config values, history file path and size, and API key status.
|
||||
|
||||
`playback_aware_radarr_discovery.sh --log`
|
||||
Verbose per-movie scoring output for both stages.
|
||||
|
||||
---
|
||||
|
||||
### playback_aware_sonarr_discovery.sh
|
||||
|
||||
`playback_aware_sonarr_discovery.sh`
|
||||
Score recently watched Emby series (weighted by user diversity), run TMDB TV
|
||||
recommendations on seeds, add candidates above threshold to Sonarr. Triggers SeriesSearch
|
||||
immediately after each successful add.
|
||||
|
||||
`playback_aware_sonarr_discovery.sh --dry-run`
|
||||
Score and rank all Stage 1 seeds and Stage 2 candidates. No Sonarr API calls. No writes
|
||||
to history file.
|
||||
|
||||
`playback_aware_sonarr_discovery.sh --status`
|
||||
Show config values, history file path and size, and API key status.
|
||||
|
||||
`playback_aware_sonarr_discovery.sh --log`
|
||||
Verbose per-series scoring output — shows user diversity, recency, and volume scores per
|
||||
seed; breadth, rating, and votes scores per candidate.
|
||||
|
||||
+33
-8
@@ -1,9 +1,11 @@
|
||||
# ━━━━━ MEDIA ━━━━━
|
||||
|
||||
Library health, consistency, and sync for a multi-server arr stack. Correct permissions
|
||||
so arrs can manage files. Junk removal so orphan detection isn't confused by scene debris.
|
||||
Library sync so every node tracks the same content. Orphan cleanup against live arr APIs
|
||||
so deleted content actually leaves disk. Emby notified automatically after every deletion.
|
||||
Library health, consistency, sync, and behavior-driven discovery for a multi-server arr
|
||||
stack. Correct permissions so arrs can manage files. Junk removal so orphan detection
|
||||
isn't confused by scene debris. Library sync so every node tracks the same content.
|
||||
Orphan cleanup against live arr APIs so deleted content actually leaves disk. Emby
|
||||
notified automatically after every deletion. Weekly discovery adds new music, movies,
|
||||
and TV shows based on what you actually play — no manual browsing required.
|
||||
|
||||
> **These scripts permanently delete files.** The arr cleanup scripts are protected by
|
||||
> multiple safety layers that must all pass before anything is touched — but dry runs and
|
||||
@@ -89,9 +91,15 @@ free overnight recovery.
|
||||
`lidarr_missing_art.sh` — fetch missing album and artist artwork from fanart.tv and
|
||||
fallback sources. Never overwrites existing files.
|
||||
|
||||
**Discovery (WIP)**
|
||||
`playback_aware_lidarr_discovery.sh` — scoring prototype for behavior-driven music
|
||||
discovery. Consumes `Kernel/decision_engine.sh`. Not yet connected to a data source.
|
||||
**Discovery**
|
||||
`playback_aware_lidarr_discovery.sh` — behavior-driven music discovery. Scores your
|
||||
Emby play history, runs Last.fm getSimilar on top artists, adds the best matches to
|
||||
Lidarr. 0–5 meaningful adds per week.
|
||||
`playback_aware_radarr_discovery.sh` — behavior-driven movie discovery. Scores recently
|
||||
watched movies, runs TMDB recommendations on seeds, adds top candidates to Radarr.
|
||||
`playback_aware_sonarr_discovery.sh` — behavior-driven TV discovery. Scores recently
|
||||
watched series weighted by user diversity, runs TMDB TV recommendations on seeds, adds
|
||||
top shows to Sonarr. Multi-user design: one person binge-watching does not dominate seeds.
|
||||
|
||||
---
|
||||
|
||||
@@ -122,6 +130,14 @@ arr_sync.sh — arrs agree on library → rsync then spreads the files
|
||||
arrs_failed_stalled_recovery.sh
|
||||
```
|
||||
|
||||
**Weekly discovery (WEEKLY_MAINTENANCE_SCRIPTS in master.conf):**
|
||||
|
||||
```
|
||||
playback_aware_lidarr_discovery.sh — score play history → Last.fm similar → add to Lidarr
|
||||
playback_aware_radarr_discovery.sh — score watch history → TMDB recommendations → add to Radarr
|
||||
playback_aware_sonarr_discovery.sh — score episode history → TMDB TV recommendations → add to Sonarr
|
||||
```
|
||||
|
||||
**Ad-hoc or separate schedule:**
|
||||
|
||||
```
|
||||
@@ -176,7 +192,9 @@ cleanly with no action. No manual `HOST1`/`HOST2` comparisons exist in any scrip
|
||||
| `lidarr_missing_art.sh` | Fetch missing album and artist artwork | Ad-hoc or separate schedule |
|
||||
| `radarr_tmdb_removed.sh` | Remove movies dropped from TMDb | Ad-hoc or weekly |
|
||||
| `sonarr_tvdb_removed.sh` | Remove series dropped from TVDB | Ad-hoc or weekly |
|
||||
| `playback_aware_lidarr_discovery.sh` | Behavior-driven music discovery scoring (WIP prototype) | Not yet scheduled |
|
||||
| `playback_aware_lidarr_discovery.sh` | Behavior-driven music discovery — Emby plays → Last.fm similar → Lidarr | Weekly via `weekly_sync_maintenance.sh` |
|
||||
| `playback_aware_radarr_discovery.sh` | Behavior-driven movie discovery — Emby watches → TMDB recommendations → Radarr | Weekly via `weekly_sync_maintenance.sh` |
|
||||
| `playback_aware_sonarr_discovery.sh` | Behavior-driven TV discovery — Emby episodes → TMDB TV recommendations → Sonarr | Weekly via `weekly_sync_maintenance.sh` |
|
||||
|
||||
---
|
||||
|
||||
@@ -206,6 +224,13 @@ Daily maintenance window (media_management.sh):
|
||||
Daily recovery:
|
||||
arrs_failed_stalled_recovery.sh ── importFailed/stalled → blocklist → re-search
|
||||
|
||||
Weekly discovery (WEEKLY_MAINTENANCE_SCRIPTS):
|
||||
playback_aware_lidarr_discovery.sh ─ Emby plays → Last.fm similar → top candidates → Lidarr
|
||||
playback_aware_radarr_discovery.sh ─ Emby watches → TMDB recommendations → top candidates → Radarr
|
||||
playback_aware_sonarr_discovery.sh ─ Emby episodes → TMDB TV recommendations → top candidates → Sonarr
|
||||
│
|
||||
└── each discovery script fires arr search immediately after successful add
|
||||
|
||||
Ad-hoc enrichment:
|
||||
lidarr_missing_art.sh ─────── discovers missing artwork → fetches from fanart.tv
|
||||
radarr_tmdb_removed.sh ────── status="deleted" → remove from Radarr + add exclusion
|
||||
|
||||
@@ -83,6 +83,33 @@
|
||||
# Recommended schedule: weekly (WEEKLY_MAINTENANCE_SCRIPTS in master.conf)
|
||||
#
|
||||
# ==============================================================================================
|
||||
# OPERATIONAL SAFEGUARDS
|
||||
# ==============================================================================================
|
||||
#
|
||||
# Root Required
|
||||
# acquire_lock and Lidarr API writes require root. Script exits cleanly if not root.
|
||||
#
|
||||
# Dry-Run Mode
|
||||
# --dry-run scores and ranks all candidates but makes no Lidarr API calls and does not
|
||||
# write to the history file. Safe to run at any time to preview what would be added.
|
||||
#
|
||||
# Add-Only
|
||||
# Only adds artists to Lidarr. Never deletes or modifies existing entries.
|
||||
#
|
||||
# Cooldown Guard
|
||||
# Candidates rejected this run are recorded in the history file and not re-evaluated
|
||||
# until LIDARR_DISCOVERY_REJECT_COOLDOWN days have elapsed.
|
||||
#
|
||||
# ==============================================================================================
|
||||
# STATE FILES
|
||||
# ==============================================================================================
|
||||
#
|
||||
# LIDARR_DISCOVERY_HISTORY (default: $DATA_DIR/lidarr_discovery_history.db)
|
||||
# Tracks added artists and rejected candidates with timestamps. Written after every
|
||||
# non-dry-run. Enforces reject cooldown and prevents re-adding items added by previous
|
||||
# runs. Safe to delete — next run starts fresh with no memory.
|
||||
#
|
||||
# ==============================================================================================
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
|
||||
@@ -84,6 +84,33 @@
|
||||
# Recommended schedule: weekly (WEEKLY_MAINTENANCE_SCRIPTS in master.conf)
|
||||
#
|
||||
# ==============================================================================================
|
||||
# OPERATIONAL SAFEGUARDS
|
||||
# ==============================================================================================
|
||||
#
|
||||
# Root Required
|
||||
# acquire_lock and Radarr API writes require root. Script exits cleanly if not root.
|
||||
#
|
||||
# Dry-Run Mode
|
||||
# --dry-run scores and ranks all candidates but makes no Radarr API calls and does not
|
||||
# write to the history file. Safe to run at any time to preview what would be added.
|
||||
#
|
||||
# Add-Only
|
||||
# Only adds movies to Radarr. Never deletes or modifies existing entries.
|
||||
#
|
||||
# Cooldown Guard
|
||||
# Candidates rejected this run are recorded in the history file and not re-evaluated
|
||||
# until RADARR_DISCOVERY_REJECT_COOLDOWN days have elapsed.
|
||||
#
|
||||
# ==============================================================================================
|
||||
# STATE FILES
|
||||
# ==============================================================================================
|
||||
#
|
||||
# RADARR_DISCOVERY_HISTORY (default: $DATA_DIR/radarr_discovery_history.db)
|
||||
# Tracks added movies and rejected candidates with timestamps. Written after every
|
||||
# non-dry-run. Enforces reject cooldown and prevents re-adding items added by previous
|
||||
# runs. Safe to delete — next run starts fresh with no memory.
|
||||
#
|
||||
# ==============================================================================================
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
|
||||
@@ -77,7 +77,7 @@
|
||||
# SONARR_DISCOVERY_MIN_RATING — min TMDB vote_average × 10 (default: 65 = 6.5/10)
|
||||
# SONARR_DISCOVERY_REJECT_COOLDOWN — days before re-evaluating a rejected show (default: 60)
|
||||
# SONARR_DISCOVERY_USER_EPISODE_CAP — max episodes per user in seed scoring (default: 8)
|
||||
# SONARR_DISCOVERY_MONITOR_MODE — Sonarr monitor mode on add (default: "future")
|
||||
# SONARR_DISCOVERY_MONITOR_MODE — Sonarr monitor mode on add: "all" or "future" (default: "all")
|
||||
# SONARR_EMBY_LIBRARIES — Emby library names to draw seeds from
|
||||
# SONARR_DISCOVERY_HISTORY — history/state file path
|
||||
#
|
||||
@@ -93,6 +93,38 @@
|
||||
# Recommended schedule: weekly (WEEKLY_MAINTENANCE_SCRIPTS in master.conf)
|
||||
#
|
||||
# ==============================================================================================
|
||||
# OPERATIONAL SAFEGUARDS
|
||||
# ==============================================================================================
|
||||
#
|
||||
# Root Required
|
||||
# acquire_lock and Sonarr API writes require root. Script exits cleanly if not root.
|
||||
#
|
||||
# Dry-Run Mode
|
||||
# --dry-run scores and ranks all candidates but makes no Sonarr API calls and does not
|
||||
# write to the history file. Safe to run at any time to preview what would be added.
|
||||
#
|
||||
# Add-Only
|
||||
# Only adds series to Sonarr. Never deletes or modifies existing entries.
|
||||
#
|
||||
# Cooldown Guard
|
||||
# Candidates rejected this run are recorded in the history file and not re-evaluated
|
||||
# until SONARR_DISCOVERY_REJECT_COOLDOWN days have elapsed.
|
||||
#
|
||||
# Monitor Mode
|
||||
# SONARR_DISCOVERY_MONITOR_MODE="all" monitors every season on add — correct for shows
|
||||
# where you want Sonarr to search back-catalogue. "future" only marks upcoming seasons;
|
||||
# use only when you intentionally want to skip existing seasons.
|
||||
#
|
||||
# ==============================================================================================
|
||||
# STATE FILES
|
||||
# ==============================================================================================
|
||||
#
|
||||
# SONARR_DISCOVERY_HISTORY (default: $DATA_DIR/sonarr_discovery_history.db)
|
||||
# Tracks added series and rejected candidates with timestamps. Written after every
|
||||
# non-dry-run. Enforces reject cooldown and prevents re-adding items added by previous
|
||||
# runs. Safe to delete — next run starts fresh with no memory.
|
||||
#
|
||||
# ==============================================================================================
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
|
||||
Reference in New Issue
Block a user