Add a unified search abstraction across metadata source plugins.
Summary:
- Introduces `SearchApiMetadataSourcePlugin` with `SearchParams`,
`get_search_query_with_filters`, and `get_search_response` hooks to
standardize album/track searches.
- Replaces ad-hoc `_search_api` and query construction logic in Deezer,
Spotify, MusicBrainz, and Discogs plugins with the new shared
implementation.
- Refactors Discogs and MusicBrainz plugins to use the new abstraction
and move provider-specific criteria/query construction into hook
methods.
- Centralizes error handling and logging in the shared search flow;
Spotify now retries authentication once on `401`, and failures cleanly
fall back to empty results at the shared layer.
Move MusicBrainzPlugin to SearchApiMetadataSourcePlugin hooks.
Keep entity mapping and criteria in provider-specific hooks.
Update typing and tests for the candidate search path.
Move search orchestration into SearchApiMetadataSourcePlugin.
Migrate Deezer, Spotify, and Discogs to provider hooks.
Keep query handling, logging, and limits centralized.
## Skip `langdetect`-dependent tests when package is unavailable
Fixes#6421.
### What changed
- Adds a `requires_import(module)` pytest marker to `conftest.py` that
skips tests when an optional dependency is not installed
- Adds an `is_importable` fixture for conditional assertions within a
test body
- Marks `TestTranslation` and other `langdetect`-dependent
tests/assertions with the new marker or fixture
- Extends `requires_import` with a `force_ci=True` kwarg — tests marked
this way are **never** skipped in `beetbox/beets` CI, ensuring coverage
where all deps are installed
- Moves marker declarations from `setup.cfg` into `pytest_configure` in
`conftest.py`
Add force_ci kwarg to requires_import pytest marker to allow tests
to run unconditionally in CI (GitHub Actions), even if the module
is not detected locally. Refactor autobpm test to use this instead
of manual env-checking at module level.
Add a `requires_import` pytest marker and `is_importable` fixture to
conditionally skip or adjust assertions based on whether optional
dependencies are available. Apply this to `langdetect`-dependent
language detection tests in lyrics and migration test suites.
## Documentation Link Maintenance
This PR audits and fixes all hyperlinks across the beets documentation.
No functional code changes — purely doc hygiene.
### What changed
- **HTTP → HTTPS**: Upgrades all `http://` links to `https://` where
supported.
- **Broken/outdated URLs**: Replaces dead or redirected links with their
current canonical targets. Key examples:
- `codecov.io` → `app.codecov.io`
- Python docs from `docs.python.org/library/` →
`docs.python.org/3/library/`
- PEP links from `python.org/dev/peps/` → `peps.python.org/`
- SourceForge project links updated to current project page URLs
- Spotify, Plex, Sonos, Discogs, IPFS, and other service URLs updated to
their current domains/paths
- Archived URLs wrapped in `web.archive.org` where the original is gone
(e.g. `echonest`, `albumart.org`, `phash`)
- **`docs/conf.py`**: Adds link-check exclusions for domains known to
block automated requests (SourceForge, fanart.tv, Imgur, Discogs
settings).
### Impact
No user-facing behaviour changes. Fixes broken links that would
frustrate contributors and users reading the docs, and unblocks the
Sphinx `linkcheck` builder from false positives.
Fixes: #6370
This PR completes the lyrics pipeline refactor around a structured
`Lyrics` value object and aligns storage, migration, and docs with that
model.
At a high level, lyrics handling is now end-to-end structured instead of
ad-hoc string/tuple flows: fetchers return `Lyrics`, translation
operates on `Lyrics`, and persistence writes both canonical text and
structured metadata.
High-level impact:
- Backends now return `Lyrics` instead of `(text, url)` tuples.
- Lyrics source metadata is no longer embedded in `item.lyrics` as a
`Source: ...` suffix.
- Lyrics metadata is stored in flexible fields:
`lyrics_backend`, `lyrics_url`, `lyrics_language`,
`lyrics_translation_language`.
- Existing libraries are automatically migrated on first run by a
one-time data migration that:
normalizes legacy mixed-content lyrics text and moves auxiliary metadata
into flex fields.
- Sync safety is improved:
with `synced` enabled, existing synced lyrics are not replaced by newly
fetched plain lyrics, even with `force`.
- LRCLib synced lyrics validation is stricter:
synced results are accepted only when the final synced timestamp is
consistent with track duration.
Docs and tests:
- Lyrics plugin docs now describe the new flexible metadata fields and
synced replacement behavior.
- Developer docs now document migration lifecycle, class-name-based
migration identity, and migration use cases.
- Changelog updated for all user-visible behavior changes.
- Tests were expanded/updated for migration behavior, backend return
types, translation behavior, synced-lyrics safety, and LRCLib duration
validation.
- Add `LyricsMetadataInFlexFieldsMigration` to extract legacy source
URLs and language metadata from lyrics text into flex attributes
- Add `Lyrics.from_legacy_text` to parse legacy lyrics format
- Move `with_row_factory` context manager up to base `Migration` class
- Rename `migrate_table` to `migrate_model` and pass model class
instead of table name string. This is so that the migration can access
both `_table` and `_flex_table` attributes.
- Make `langdetect` import optional in `Lyrics.__post_init__`: users may
not have have the dependency installed, and we do not want the
migration to fail because of that.
- Move `BACKEND_BY_NAME` to module level for use outside plugin class
* Introduce a `Lyrics` dataclass to carry text, source URL, and language
metadata through fetch, translation, and storage paths.
* Return `Lyrics` from backends and plugin lookup methods instead of raw
tuples/strings.
* Store backend name in `lyrics_source` derived from fetched URL root
domain.
* Simplify translator flow to operate on `Lyrics`, reuse line splitting,
append translations in-place, and record translation language
metadata.
When lyrics.synced is enabled, avoid replacing existing synced lyrics with
newly fetched unsynced lyrics, even with force enabled.
Allow replacement when the new lyrics are also synced, or when synced mode
is disabled.
Introduce a new lastgenre `cleanup_existing` flag.
It handles the case where canonicalization is desired on existing tags.
The new logic triggers if:
- `force`: False
- `cleanup_existing: True
Depending on whether `whitelist: True` or `canonical: True`, the genres
are then canonicalized and/or whitelisting is applied
Fix extension substitution inside path of the exported playlist.
Before this, the exported playlist contained relative paths pointing to
the
converted files BUT the extension were not substituted comparing to
before and
the after the conversion. Therefore, running the playlist will fail for
files
which have been converted and where extension have changed.
Example:
1. Convert `/path/to/library/artist.flac` to
`/path/to/converted/artist.mp3` using the `-m playlist.m3u` command-line
flag.
2. Open the generated playlist, and find the incorrect path
`/path/to/converted/artist.flac` inside.
