meta: expose Teensy Audio dependency to PlatformIO LDF and fbuild

[zackees]

Context

FastLED’s Teensy audio support currently detects <Audio.h> and uses Teensy Audio types from the audio-input implementation, but the dependency is not guaranteed to be visible early enough to every build backend’s dependency scanner.

PlatformIO discovers framework libraries through LDF scanning. fbuild uses its own header/dependency selection. If Audio.h is not present in the normal FastLED platform include chain, either backend can omit the Teensy Audio implementation sources even though FastLED’s audio wrappers later reference symbols such as:

• AudioInputI2S::begin()
• AudioInputI2S2::begin()
• AudioInputI2S::update()
• vtable for AudioInputI2S
• vtable for AudioInputI2S2

This caused the Teensy 4.1 HydroPack link failure tracked by FastLED/FastLED#3685.

The existing include seam is:

• src/FastLED.h
• src/platforms/ldf_headers.h
• src/platforms/arm/teensy/ldf_headers.h

Proposal

Add a Teensy-specific, guarded <Audio.h> include to FastLED’s platform include chain, preferably through platforms/arm/teensy/ldf_headers.h or the adjacent Teensy platform header selected by FastLED.h.

The include should be active when the expected Teensy Audio header is available, so that both dependency systems see it:

• PlatformIO LDF selects the bundled Teensy Audio library.
• fbuild’s header scanner selects and compiles the bundled Audio implementation sources.

This is intentionally a small dependency-discovery shim. It should not manually compile Audio sources, add a broad Teensy framework allowlist, or bypass LTO/section garbage collection. The existing TEENSY_AUDIO_LIBRARY_AVAILABLE guards and no-op behavior for missing headers must remain intact.

Measured baseline

On Teensy 4.1:

Build	Flash	RAM
Blink without Audio	100,352 bytes	72,352 bytes
Blink with Teensy Audio selected	100,352 bytes	72,544 bytes

The Audio-enabled build compiled the bundled Audio sources successfully. Final deployed flash size was unchanged, indicating that LTO/section GC removed unused Audio code. RAM increased by 192 bytes and should be tracked as an explicit cost.

Acceptance criteria

• FastLED.h causes the Teensy-specific dependency-discovery path to expose <Audio.h> when the header exists.
• PlatformIO LDF selects the Teensy Audio library for a Teensy sketch that includes only FastLED.h.
• fbuild selects the same Audio library under the same conditions.
• A Teensy build using AudioInputI2S and/or AudioInputI2S2 links successfully under both supported build backends.
• A minimal Teensy 4.1 Blink build can include the dependency-discovery shim without increasing deployed flash/HEX size.
• The measured RAM impact is documented and remains within the board budget.
• Missing Teensy Audio headers continue to produce the intended loud warning/no-op behavior rather than a compile failure.
• The change does not restore the old behavior of compiling every unrelated Teensy framework library.
• FastLED CI covers both a minimal Teensy Blink size regression and a Teensy audio consumer such as HydroPack or the existing audio example.

Related issues

• Teensy 4.x: SPI framework library compiled but not linked — undefined references to SPIClass::* at link time #284 — Teensy framework library compiled but not linked.
• feat(library-selection): Rust-native LDF-style transitive header scanner, zccache-backed #205 — LDF-style transitive framework-library selection foundation.
• fbuild deficiency vs PlatformIO+Teensyduino: CMSIS-DSP not auto-linked for Teensy 3.x/4.x #300 — Teensy CMSIS-DSP auto-linking for Audio FFT dependencies.
• teensy30/LC: Teensy orchestrator compiles unreferenced framework libraries (FNET, Snooze, RadioHead, mbedtls) — causes .bss / .dmabuffers RAM overflow #204 — prior eager framework-library behavior causing Teensy RAM overflow.
• CI: teensy41 build fails to link HydroPack example (pre-existing on master since #3683) FastLED#3685 — HydroPack Teensy link failure that exposed the Audio case.

[zackees]

FastLED implementation is in FastLED/FastLED#3692.

The intended result is now explicit: FastLED.h reaches a Teensy-specific active <Audio.h> include when the existing audio/header guards pass, allowing both PlatformIO LDF and fbuild to select the bundled Teensy Audio implementation. This is dependency discovery only; it preserves LTO/section GC and does not broadly eager-link unrelated framework libraries.

Local evidence: Teensy 4.1 Blink compiled Audio sources and retained the measured 100,352-byte flash image; the Teensy AudioInput example linked successfully.

[zackees]

Implemented and validated via merged FastLED/FastLED#3692.

Final evidence on current FastLED master:

• bash compile teensy41 --examples Blink passed; the fbuild compile database contains Teensy Audio sources, including input_i2s.cpp and input_i2s2.cpp; flash is 100,352 bytes and RAM is 72,544 bytes.
• bash compile teensy41 --examples AudioInput passed and linked successfully.

The intended result is achieved: FastLED.h exposes a guarded active <Audio.h> include through the Teensy platform chain, making the dependency visible to both PlatformIO LDF and fbuild without manually eager-linking unrelated framework libraries.

[zackees]

Follow-up validation completed after the tracker closure:

• ci(teensy): add AudioInput parity coverage FastLED#3695 is merged on master; the nightly fbuild/PlatformIO parity matrix now runs teensy41 for both Blink and AudioInput.
• On the exact merged tree, both bash compile teensy41 --backend platformio --examples Blink and bash compile teensy41 --backend platformio --examples AudioInput passed.
• PlatformIO LDF selected Audio @ 1.3 for AudioInput, compiling and linking both input_i2s.cpp and input_i2s2.cpp.

Together with #3692's guarded include, the FastLED CI coverage and both-backend acceptance criteria are complete.