feat: EXCLUDE_LABELS env var for per-item opt-out

Plex items carrying any label listed in EXCLUDE_LABELS are skipped on
both the apply path (ProcessAllItems, ProcessSingleItem) and the removal
path (RemoveKeywordsFromItems). Match is case-insensitive; whitespace
and empty entries in the CSV are ignored.

Motivating use case: home videos (e.g. weddings) sitting alongside real
movies in a Movies library were getting matched to unrelated TMDb titles
and tagged with their keywords. Labelarr already manipulates Plex labels,
so making a label the per-item opt-out is the natural design - set-and-
forget per item via Plex UI, no env var sprawl, survives metadata
refreshes.

Behavior:
- Config: new `ExcludeLabels []string` loaded via parseCSV.
- Processor: precomputes a lowercased map[string]struct{} once in
  NewProcessor; `isExcludedByLabel(item)` is O(item.labels).
- Logging: `[INFO] EXCLUDE_LABELS active - items tagged with any of
  [...] will be skipped` at startup when non-empty; per-item
  `[SKIP] %s (%d) excluded by label %q (EXCLUDE_LABELS)` under
  `VERBOSE_LOGGING=true` (and unconditionally on the webhook single-
  item path).
- Tests: 9 sub-tests covering nil config, no-labels item, exact match,
  both casing directions, multi-label, no-match, whitespace
  normalization, and empty-string-in-CSV.

Also documents `MOVIE_LIBRARY_EXCLUDE` / `TV_LIBRARY_EXCLUDE` in the
README env var table (added in 1.3.0 but only mentioned in the changelog
until now).

Author: nullable-eth

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+- `EXCLUDE_LABELS` environment variable (default empty): comma-separated list of Plex labels that mark items as opted-out of labelarr. Items carrying any of these labels are skipped during both apply and removal passes. Case-insensitive; surrounding whitespace and empty values in the CSV are ignored. Logged at startup when active (`[INFO] EXCLUDE_LABELS active - items tagged with any of [...] will be skipped`) and per skipped item under `VERBOSE_LOGGING=true`.
+
+### Documentation
+- README `Library Selection` section now documents `MOVIE_LIBRARY_EXCLUDE` and `TV_LIBRARY_EXCLUDE`, which were added in 1.3.0 but only appeared in the changelog.
+
 ## [1.3.2] - 2026-04-21
 
 ### Security

README.md

@@ -92,6 +92,14 @@ Pick one approach per media type:
 | `TV_PROCESS_ALL=true` | Process all TV show libraries |
 | `TV_LIBRARY_ID=2` | Process a specific TV library by ID |
 
+Optionally narrow what gets processed within those libraries:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MOVIE_LIBRARY_EXCLUDE` | (empty) | Comma-separated Plex library **IDs** to skip when `MOVIE_PROCESS_ALL=true` (e.g. `MOVIE_LIBRARY_EXCLUDE=8,12`). Useful for keeping a "Home Videos" library out of the scan. |
+| `TV_LIBRARY_EXCLUDE` | (empty) | Same as above for TV libraries. |
+| `EXCLUDE_LABELS` | (empty) | Comma-separated **per-item opt-out** label list. Any Plex item carrying one of these labels is skipped on both apply and removal paths. Case-insensitive. Example: `EXCLUDE_LABELS=labelarr:skip,home video`. Tag the offending items in Plex (Edit -> Tags -> Labels) and labelarr will leave them alone. |
+
 ### Optional
 
 | Variable | Default | Description |

internal/config/config.go

@@ -21,6 +21,7 @@ type Config struct {
 	TVLibraryID            string
 	TVProcessAll           bool
 	TVLibraryExclude       []string
+	ExcludeLabels          []string
 	WebhookOnly            bool
 	UpdateField            string
 	RemoveMode             string
@@ -78,6 +79,7 @@ func Load() *Config {
 		TVLibraryID:            os.Getenv("TV_LIBRARY_ID"),
 		TVProcessAll:           getBoolEnvWithDefault("TV_PROCESS_ALL", false),
 		TVLibraryExclude:       parseCSV(os.Getenv("TV_LIBRARY_EXCLUDE")),
+		ExcludeLabels:          parseCSV(os.Getenv("EXCLUDE_LABELS")),
 		WebhookOnly:            getBoolEnvWithDefault("WEBHOOK_ONLY", false),
 		UpdateField:            getEnvWithDefault("UPDATE_FIELD", "label"),
 		RemoveMode:             os.Getenv("REMOVE"),

internal/media/processor.go

@@ -3,6 +3,7 @@ package media
 import (
 	"fmt"
 	"regexp"
+	"sort"
 	"strings"
 	"sync"
 	"time"
@@ -58,6 +59,10 @@ type Processor struct {
 	cacheMu      sync.RWMutex
 	processingMu sync.Mutex
 	processing   map[string]bool
+
+	// excludeLabels is the lowercased set of Plex labels that mark items as opted-out.
+	// Built once from config.ExcludeLabels in NewProcessor.
+	excludeLabels map[string]struct{}
 }
 
 // NewProcessor creates a new generic media processor
@@ -76,15 +81,25 @@ func NewProcessor(cfg *config.Config, clients Clients) (*Processor, error) {
 		}
 	}
 
+	excludeLabels := make(map[string]struct{}, len(cfg.ExcludeLabels))
+	for _, l := range cfg.ExcludeLabels {
+		t := strings.TrimSpace(strings.ToLower(l))
+		if t == "" {
+			continue
+		}
+		excludeLabels[t] = struct{}{}
+	}
+
 	processor := &Processor{
-		config:       cfg,
-		plexClient:   plexClient,
-		tmdbClient:   tmdbClient,
-		radarrClient: radarrClient,
-		sonarrClient: sonarrClient,
-		storage:      stor,
-		keywordCache: make(map[string][]string),
-		processing:   make(map[string]bool),
+		config:        cfg,
+		plexClient:    plexClient,
+		tmdbClient:    tmdbClient,
+		radarrClient:  radarrClient,
+		sonarrClient:  sonarrClient,
+		storage:       stor,
+		keywordCache:  make(map[string][]string),
+		processing:    make(map[string]bool),
+		excludeLabels: excludeLabels,
 	}
 
 	// Initialize exporter if export is enabled
@@ -108,9 +123,33 @@ func NewProcessor(cfg *config.Config, clients Clients) (*Processor, error) {
 		fmt.Printf("[SYNC] Running in ephemeral mode - no persistent storage (set DATA_DIR to enable)\n")
 	}
 
+	if len(excludeLabels) > 0 {
+		labels := make([]string, 0, len(excludeLabels))
+		for l := range excludeLabels {
+			labels = append(labels, l)
+		}
+		sort.Strings(labels)
+		fmt.Printf("[INFO] EXCLUDE_LABELS active - items tagged with any of %v will be skipped (case-insensitive)\n", labels)
+	}
+
 	return processor, nil
 }
 
+// isExcludedByLabel reports whether the item carries any Plex label listed in
+// EXCLUDE_LABELS. Match is case-insensitive. When excluded, returns the actual
+// label tag from Plex (preserving the original casing) for logging.
+func (p *Processor) isExcludedByLabel(item MediaItem) (string, bool) {
+	if len(p.excludeLabels) == 0 {
+		return "", false
+	}
+	for _, lbl := range item.GetLabel() {
+		if _, ok := p.excludeLabels[strings.ToLower(lbl.Tag)]; ok {
+			return lbl.Tag, true
+		}
+	}
+	return "", false
+}
+
 // GetExporter returns the exporter instance if export is enabled
 func (p *Processor) GetExporter() *export.Exporter {
 	return p.exporter
@@ -242,6 +281,11 @@ func (p *Processor) ProcessSingleItem(ratingKey, libraryID string, mediaType Med
 
 	fmt.Printf("[WEBHOOK] Processing single item: %s (%d)\n", item.GetTitle(), item.GetYear())
 
+	if tag, skip := p.isExcludedByLabel(item); skip {
+		fmt.Printf("[SKIP] %s (%d) excluded by label %q (EXCLUDE_LABELS)\n", item.GetTitle(), item.GetYear(), tag)
+		return nil
+	}
+
 	tmdbID := p.extractTMDbID(item, mediaType)
 	if tmdbID == "" {
 		fmt.Printf("[SKIP] No TMDb ID found for: %s\n", item.GetTitle())
@@ -394,6 +438,14 @@ func (p *Processor) ProcessAllItems(libraryID string, libraryName string, mediaT
 		for _, item := range b.items {
 			processedCount++
 
+			if tag, skipExcl := p.isExcludedByLabel(item); skipExcl {
+				if p.config.VerboseLogging {
+					fmt.Printf("   [SKIP] %s (%d) excluded by label %q (EXCLUDE_LABELS)\n", item.GetTitle(), item.GetYear(), tag)
+				}
+				skippedItems++
+				continue
+			}
+
 			if totalCount > 100 {
 				progress := (processedCount * 100) / totalCount
 				if progress >= lastProgressReport+10 {
@@ -694,6 +746,14 @@ func (p *Processor) RemoveKeywordsFromItems(libraryID string, mediaType MediaTyp
 				fmt.Printf("[STATS] Removal Progress: %d/%d (%.1f%%)\n", processedCount, len(items), float64(processedCount)/float64(len(items))*100)
 			}
 
+			if tag, skipExcl := p.isExcludedByLabel(item); skipExcl {
+				if p.config.VerboseLogging {
+					fmt.Printf("   [SKIP] %s (%d) excluded by label %q (EXCLUDE_LABELS)\n", item.GetTitle(), item.GetYear(), tag)
+				}
+				skippedCount++
+				continue
+			}
+
 			tmdbID := p.extractTMDbID(item, mediaType)
 			if tmdbID == "" {
 				skippedCount++

internal/media/processor_test.go

@@ -1,6 +1,11 @@
 package media
 
-import "testing"
+import (
+	"strings"
+	"testing"
+
+	"github.com/nullable-eth/labelarr/internal/plex"
+)
 
 func TestExtractTMDbIDFromPath(t *testing.T) {
 	tests := []struct {
@@ -272,3 +277,97 @@ func TestExtractTMDbIDFromPathEdgeCases(t *testing.T) {
 		})
 	}
 }
+
+func TestIsExcludedByLabel(t *testing.T) {
+	tests := []struct {
+		name           string
+		excludeLabels  []string
+		itemLabels     []string
+		wantSkip       bool
+		wantMatchedTag string
+	}{
+		{
+			name:          "no exclude labels configured",
+			excludeLabels: nil,
+			itemLabels:    []string{"labelarr:skip"},
+			wantSkip:      false,
+		},
+		{
+			name:          "item has no labels",
+			excludeLabels: []string{"labelarr:skip"},
+			itemLabels:    nil,
+			wantSkip:      false,
+		},
+		{
+			name:          "exact match",
+			excludeLabels: []string{"labelarr:skip"},
+			itemLabels:    []string{"labelarr:skip"},
+			wantSkip:      true, wantMatchedTag: "labelarr:skip",
+		},
+		{
+			name:          "case-insensitive match (config upper, label lower)",
+			excludeLabels: []string{"LABELARR:SKIP"},
+			itemLabels:    []string{"labelarr:skip"},
+			wantSkip:      true, wantMatchedTag: "labelarr:skip",
+		},
+		{
+			name:          "case-insensitive match (config lower, label mixed)",
+			excludeLabels: []string{"home video"},
+			itemLabels:    []string{"Home Video"},
+			wantSkip:      true, wantMatchedTag: "Home Video",
+		},
+		{
+			name:          "multiple exclude labels, second one matches",
+			excludeLabels: []string{"foo", "labelarr:skip", "bar"},
+			itemLabels:    []string{"family", "labelarr:skip"},
+			wantSkip:      true, wantMatchedTag: "labelarr:skip",
+		},
+		{
+			name:          "no match",
+			excludeLabels: []string{"labelarr:skip"},
+			itemLabels:    []string{"family", "vacation"},
+			wantSkip:      false,
+		},
+		{
+			name:          "whitespace and casing in config are normalized",
+			excludeLabels: []string{"  Labelarr:Skip  "},
+			itemLabels:    []string{"labelarr:skip"},
+			wantSkip:      true, wantMatchedTag: "labelarr:skip",
+		},
+		{
+			name:          "empty string in config is ignored",
+			excludeLabels: []string{"", "labelarr:skip"},
+			itemLabels:    []string{""},
+			wantSkip:      false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			// Build the lowercased set the way NewProcessor does.
+			set := make(map[string]struct{})
+			for _, l := range tc.excludeLabels {
+				k := strings.TrimSpace(strings.ToLower(l))
+				if k == "" {
+					continue
+				}
+				set[k] = struct{}{}
+			}
+			p := &Processor{excludeLabels: set}
+
+			plexLabels := make([]plex.Label, 0, len(tc.itemLabels))
+			for _, l := range tc.itemLabels {
+				plexLabels = append(plexLabels, plex.Label{Tag: l})
+			}
+			item := plex.Movie{Title: "test", Year: 2020, Label: plexLabels}
+
+			gotTag, gotSkip := p.isExcludedByLabel(item)
+			if gotSkip != tc.wantSkip {
+				t.Errorf("skip=%v, want %v (matched tag %q)", gotSkip, tc.wantSkip, gotTag)
+			}
+			if tc.wantSkip && gotTag != tc.wantMatchedTag {
+				t.Errorf("matched tag=%q, want %q", gotTag, tc.wantMatchedTag)
+			}
+		})
+	}
+}