yamaha-remote-control-api

Licensed under MIT. See LICENSE.

Transport-agnostic core library for controlling Yamaha AV receivers via the legacy YamahaRemoteControl XML-over-HTTP protocol. Provides XML parsing, command building, and a high-level receiver API.

Used by the GNOME Shell extension gnome-yamaha-avr to control the developer's receiver from an HTPC.

Note: This targets Yamaha's old XML-over-HTTP control API (POST to /YamahaRemoteControl/ctrl). The API surface was derived from the Unit_Description XML spec downloaded directly from the receiver. Newer Yamaha models use "MusicCast" — a REST-based protocol — which is not supported by this package.

Dependencies

• Node.js and npm — for building and package management
• GJS (GNOME JavaScript runtime) — required to run tests and the sample application
• TypeScript — installed automatically via npm install

No runtime npm dependencies. TypeScript is the only dev dependency.

Development

After cloning:

npm install             # install dev dependencies
npm run build           # compile TypeScript and run unit tests

npm run build compiles src/ → dist/ with tsc, then runs the GJS unit tests. It aborts on any failure.

To compile without running tests:

npm run build:notest

Sample Application

An interactive GJS console app lives in examples/yamaha-api-sample.ts. It builds menus dynamically from the API object and lets you call receiver functions interactively.

# Build first (the sample imports from dist/)
npm run build:notest

# Run (requires GJS and a receiver on the network)
gjs -m examples/yamaha-api-sample.ts

Note: The sample uses gi:// imports (GLib, Gio) for stdin and the main loop. It is a GJS application, not a Node.js script.

Build local npm package

npm run build:pack      # build, test, bump patch version, create tarball

Install the tarball from another project:

npm install ./yamaha-remote-control-api-0.1.0.tgz

Publish to npm

npm run build:publish   # build, test, bump patch version, publish

Consuming this package

This package is typically added as a dev dependency and bundled at build time (e.g. with esbuild). Three options:

Method	package.json	When to use
Local source	"yamaha-remote-control-api": "file:../yamaha-remote-control-api"	Co-development (default)
Local tarball	"yamaha-remote-control-api": "file:./yamaha-remote-control-api-0.1.0.tgz"	Testing a release
Published	"yamaha-remote-control-api": "^0.1.0"	CI / stable builds

AI Disclosure

This library is a result of my experiments with various AI models using Github Copilot in VS Code. Started with cheapest models. Felt like slot machine coding. (One more prompt. If I write this word it surely will pay out). GTP5 was more like vibe coding. Claude Opus 4.6 could probably do a better version from scratch based on 1 sentence prompt and no instructions. But that is no fun and scales badly. Currently experimenting with instructions and plans to in order to enable cheapest models to produce value.