foobar2000 Component Development Skills

This repository packages task-focused Codex skills for foobar2000 component development and offline technical lookup.

See offline-coverage-matrix.md for the current offline snapshot dates, covered fields, and live-check boundaries.

Skills

• foobar2000-sdk-component-dev: SDK-oriented C++ component development, services, callbacks, configuration, threading, exceptions, build notes, and local SDK search.
• foobar2000-titleformat-query: title formatting, query syntax, command-line syntax, examples, and runtime expression debugging.
• foobar2000-component-research: component catalog lookup, category comparison, installation, publishing, and architecture compatibility.

Local SDK Setup

The foobar2000 application and SDK are not bundled here. Configure a local SDK without changing system-wide environment variables:

1. Copy .local.example/foobar2000-paths.json to .local/foobar2000-paths.json.
2. Set sdk_root to your downloaded SDK directory.
3. Leave values as placeholders if a path is not needed.

The SDK scripts resolve paths in this order:

• --sdk-root command-line argument.
• FOOBAR2000_SDK_ROOT or FB2K_SDK_ROOT.
• .local/foobar2000-paths.json.
• .local/foobar2000-sdk-root.txt.
• Automatic probing for SDK-* or foobar2000*SDK* directories near the repo or current working directory.

Generate a local, ignored SDK symbol index when needed:

python foobar2000-sdk-component-dev/scripts/build_sdk_symbol_index.py

Use --include-sdk-root-path only for ignored local output; it writes the resolved machine-specific SDK path into the generated index, so do not commit that output.

Search bundled references and a configured SDK with PowerShell-safe quoting:

python foobar2000-sdk-component-dev/scripts/search_foobar2000.py service_factory
python foobar2000-titleformat-query/scripts/search_runtime_docs.py '$if'
python foobar2000-component-research/scripts/search_component_catalog.py --tag DSP
python foobar2000-component-research/scripts/search_component_catalog.py --tag "Default UI element" --details "Windows ARM"
python foobar2000-component-research/scripts/search_component_catalog.py foo_abx --details-only

Refresh generated offline indexes when maintaining the skill:

python foobar2000-component-research/scripts/refresh_official_component_catalog.py
python foobar2000-sdk-component-dev/scripts/refresh_official_sdk_snapshots.py
python foobar2000-titleformat-query/scripts/build_runtime_token_index.py

The component catalog refresh retries transient request failures, validates nonempty catalog/tag/detail parsing, and writes only after every requested result passes. Partial checks with --tag or --detail-limit require explicit output paths so they cannot replace the default full snapshots. The SDK refresh likewise rejects empty or structurally incomplete SDK, changelog, PDB, and support parsing before writing.

Run the targeted script regression tests after changing snapshot search or refresh behavior:

python -m unittest discover -s tests -v

Official foobar2000 Links

• SDK download and documentation entry: https://www.foobar2000.org/SDK
• Developer documentation entry: https://www.foobar2000.org/RTFM
• SDK change log: https://www.foobar2000.org/changelog-sdk
• Public debug symbols: https://www.foobar2000.org/PDB/
• Component catalog: https://www.foobar2000.org/components
• Support: https://www.foobar2000.org/support

Repository Boundaries

Keep local paths, generated SDK indexes, and downloaded foobar2000 or SDK files under .local/ or outside the repository.

See LICENSE for excluded third-party material and the MIT/GFDL split. See NOTICE.md for source attribution.