LIDARR WANTED ALBUMS REPORT
Export-LidarrWanted.ps1
Version 2.3

DESCRIPTION
===========
Export-LidarrWanted.ps1 creates a searchable, mobile-friendly HTML report of albums currently listed by Lidarr as Missing or Cutoff Unmet.

The script also maintains persistent CSV files so you can research albums over time without losing your work when the report is regenerated. You can track stores/websites, prices, URLs, formats, availability, local vs. online sources, notes, and albums that have already been ordered.

The generated WantedAlbums.html file is self-contained. It can be opened locally, copied to a phone/tablet, or uploaded to a web server. The report does not need access to Lidarr after it has been generated. External source URLs require Internet access when opened.


REQUIREMENTS
============
- Windows
- PowerShell
- Lidarr
- A Lidarr API key
- Excel, LibreOffice, or another CSV editor is optional but recommended for editing research data


CONFIGURATION
=============
Open Export-LidarrWanted.ps1 and review the CONFIG section near the top.

Set your Lidarr API key:

    $ApiKey = "YOUR-LIDARR-API-KEY"

Set your Lidarr URL if it differs from the default:

    $Lidarr = "http://localhost:8686"

Your Lidarr API key can be found under:

    Lidarr -> Settings -> General -> Security -> API Key

By default, all generated files are saved in the same folder as Export-LidarrWanted.ps1 by using $PSScriptRoot. You can change any of these paths if you prefer another location:

    $OutputFile
    $SearchCsvFile
    $TrackingCsvFile
    $SourcesCsvFile

Stale research is controlled by:

    $StaleResearchDays = 30

Change 30 to the number of days you prefer. Research with a LastChecked date older than this value can be identified using the Stale filter in the HTML report.


RUNNING THE SCRIPT
==================
Run the script from PowerShell:

    .\Export-LidarrWanted.ps1

The script queries Lidarr and generates/updates the following files:

    WantedAlbums.html
    WantedAlbums-Search.csv
    WantedAlbums-Tracking.csv
    WantedAlbums-Sources.csv


WANTEDALBUMS.HTML
=================
This is the main report.

It includes:
- Missing albums
- Cutoff Unmet albums
- Search
- Sortable columns
- Group by Artist
- Research filtering
- Maximum Best Price filtering
- Local/Online source filtering
- Stale research filtering
- Ordered/Not Ordered filtering
- Multiple sources per album
- Best Price calculation
- Prominent ORDERED status
- Summary counts
- Mobile-friendly formatting

An album marked Ordered remains visible as ORDERED while Lidarr still considers it wanted. This helps prevent accidentally purchasing the same album again while waiting for an online order to arrive.

Once the album is received/imported and Lidarr no longer reports it as wanted, it disappears from the active HTML report naturally. Its persistent tracking and research data remain in the CSV files.


WANTEDALBUMS-TRACKING.CSV
=========================
This file is maintained automatically by the script.

Normally, DO NOT edit it manually.

It tracks albums seen by the script and contains fields such as:

    AlbumKey
    LidarrId
    Artist
    Album
    Year
    Active
    FirstSeen
    LastSeen
    LastType

When an album disappears from Lidarr's wanted list, its tracking record is retained and marked inactive. If it becomes wanted again later, the existing record is reactivated.

This persistence allows your research to survive changes in Lidarr's current wanted state.


WANTEDALBUMS-SOURCES.CSV
========================
This is the CSV you edit to maintain album research.

The script automatically creates one blank source row for each tracked album. Descriptive Artist/Album/Year information may be refreshed from Lidarr on future runs, but your manually entered research fields are preserved.

FIELDS
------
AlbumKey
    Internal stable identifier used to associate source rows with an album.
    Do not manually change this value.

Artist / Album / Year
    Descriptive fields maintained by the script.

Source
    Store, website, seller, or other source.
    Examples: Discogs, Bandcamp, Amazon, Local Record Store

Price
    Price found at the source. The HTML report calculates Best Price using the lowest numeric price entered for the album.

URL
    Direct link to the album/listing. It becomes clickable in the HTML report.

Format
    Examples: CD, FLAC, MP3, Vinyl

LastChecked
    Date the source/price/availability was last verified.
    A simple date such as 09/07/2026 is recommended.

Availability
    Examples: Yes, No, Backordered

LocationType
    Use Local or Online.

PurchaseStatus
    Leave blank when not purchased.
    Set to Ordered after purchasing an album that has not yet arrived/imported.

    Ordered persists across future script runs and causes the album to display prominently as ORDERED in the HTML report.

Notes
    Any additional information you want to retain.
    Examples: Includes shipping, used condition, deluxe edition, seller information, bonus tracks, etc.


ADDING MULTIPLE SOURCES
=======================
To track more than one source for an album, duplicate that album's entire row in WantedAlbums-Sources.csv and edit the research fields on the duplicate.

IMPORTANT: Keep the same AlbumKey on every duplicated source row for that album.

Example:

    Example Artist | Example Album | Bandcamp          | $9.99  | FLAC | Online
    Example Artist | Example Album | Discogs           | $14.99 | CD   | Online
    Example Artist | Example Album | Local Record Store| $11.99 | CD   | Local

The report will associate all of these rows with the same album and calculate the lowest numeric price as Best Price.

If you purchase from one of the sources, set PurchaseStatus to Ordered on the source row you actually purchased from. The entire album will then display as ORDERED while the expanded source information shows which source was used.


TYPICAL WORKFLOW
================
1. Run Export-LidarrWanted.ps1.
2. Open WantedAlbums.html to review albums Lidarr wants.
3. Research an album.
4. Enter research in WantedAlbums-Sources.csv.
5. Duplicate the album row if you want to track additional sources.
6. Run the script again to regenerate the HTML report.
7. If you purchase an album, set PurchaseStatus to Ordered on the purchased source row.
8. Run the script again. The album will display prominently as ORDERED.
9. When the album arrives, import it into your music library/Lidarr workflow.
10. When Lidarr no longer reports it as wanted, it disappears from the active report automatically.


PERSISTENCE AND BACKUPS
=======================
The HTML and simple search CSV are generated outputs and can be recreated.

The important persistent files are:

    WantedAlbums-Tracking.csv
    WantedAlbums-Sources.csv

WantedAlbums-Sources.csv is especially important because it contains your manually entered research. Back it up regularly.

Do not delete these files before a normal run unless you intentionally want to reset their persistent data.


WANTEDALBUMS-SEARCH.CSV
=======================
WantedAlbums-Search.csv contains a simplified export of the current wanted Artist/Album information. It is optional and is provided as a convenient generic CSV for use with other scripts, searches, spreadsheets, or personal workflows.


PRIVACY / PUBLIC WEB USE
========================
Before publishing WantedAlbums.html publicly, review the generated report. Information entered in WantedAlbums-Sources.csv, including URLs and Notes, is embedded in the HTML report.

Never publish your Lidarr API key.

The generated HTML report does not require or expose the API key simply to be viewed. The API key belongs only in the PowerShell script used to query your Lidarr server.
