Asyncio library for Yamaha MusicCast devices

aiomusiccast-co is a maintained fork of aiomusiccast, the library behind Home Assistant's Yamaha MusicCast integration. Upstream is no longer actively maintained, so this fork continues from its last release (0.15.0) under a new name.

What's new compared to aiomusiccast 0.15.0

• Actual volume: read and set the zone volume in dB, matching the receiver's display.
• Zone scenes: list a zone's scenes and recall them.
• Surround AI: on/off control for receivers that support it.
• Speaker pattern and device category support.
• Fixes for devices that omit the zone, input or sound program lists.
• A longer HTTP timeout (8s), and the package now ships py.typed.

See the changelog for details.

Setup

Requirements

• Python 3.11+

Installation

$ pip install aiomusiccast-co

or add it to your uv project:

$ uv add aiomusiccast-co

The distribution is aiomusiccast-co; the import name is aiomusiccast_co. It installs alongside upstream aiomusiccast without conflict.

Usage

import asyncio

from aiohttp import ClientSession

from aiomusiccast_co import MusicCastDevice


async def main() -> None:
    async with ClientSession() as session:
        device = MusicCastDevice("192.168.1.50", session)
        await device.fetch()

        print(device.data.model_name, device.data.network_name)
        for zone_id, zone in device.data.zones.items():
            print(zone_id, zone.power, zone.current_volume)

        await device.set_volume_level("main", 0.3)


asyncio.run(main())

To get push updates instead of polling, register a callback with device.register_callback(...) and call await device.device.enable_polling(), which starts the UDP event listener.

Migrating from aiomusiccast

Install aiomusiccast-co in place of aiomusiccast and change the imports:

# before
from aiomusiccast import MusicCastDevice
# after
from aiomusiccast_co import MusicCastDevice

The API is otherwise the same as upstream 0.15.0, with the additions above.

Contributing

See CONTRIBUTING.md.

Credits

Originally written by Tom Schneider (@vigonotion) and contributors; pyamaha.py is based on rsc-dev/pyamaha. Released under the MIT License.