docs: guides for running multiple AirPlay 2 instances and splitting a surround card

[haavar]

What this is

Two new ADVANCED TOPICS guides for building a multi-room AirPlay 2 system, plus an index entry and a pointer from AIRPLAY2.md:

• RunningMultipleInstances.md — running one AirPlay 2 instance per room on a single host, VM or set of containers. Each instance gets a name and a distinct port (or address); the AirPlay 2 device id and the nqptp shared-memory name are derived from the name, so several instances share one configuration file and differ only in name, port and output device. Covers the one-shared-nqptp model, per-room Avahi, a container example, and pointers to the ALSA guide.
• SplittingASurroundCard.md — carving one multichannel ALSA card into several independent per-room stereo PCMs with dshare/bindings (and plug), including the shared-IPC requirement for doing the split across containers, and a note on pinning USB cards by name.

It also updates AIRPLAY2.md: the old "multiple instances can not be hosted on the same system" line is replaced by a pointer to the new guide.

Depends on two open PRs

RunningMultipleInstances.md documents the system as it will behave once these are merged, so this should land after them:

• Derive per-instance AirPlay 2 identity from the instance name #2287 — derive the per-instance AirPlay 2 identity (device id + nqptp shared-memory name) from the instance name. The guide's "identity follows the name" model relies on this.
• docker: add ENABLE_NQPTP to opt out of starting NQPTP #2288 — ENABLE_NQPTP in the container launcher. The guide's container example sets ENABLE_NQPTP=0 on the room containers so a single shared nqptp serves them all.

SplittingASurroundCard.md is pure ALSA configuration and has no dependency on either PR.

I've written the guides against the merged behaviour rather than hedging every line with version caveats; happy to add a "requires version X" note once there's a release, or to hold this until #2287 and #2288 are in.

[mikebrady]

Thanks again.

[noelhibbard]

Thanks @haavar for all your PRs. This weekend I'm going to switch my docker compose to no longer use macvlan and use env vars to set the name, device and port with one common config.

[haavar]

Sure. I just converted my setup to port based and config template today using the development branch. No local changes. I made some updates to the instructions in another PR. There is probably a more elegant way to run avahi and nqptp, but this works.

If you are using mqtt to send updates to home assistant, you need to delete the mqtt devices in HA to get the updates. The devices gets recreated, and I did not have to make any other changes.