Chromecast Device Emulator

The emulator works by REPLAYING IPC (Inter-Process Communication) messages between a sender and a receiver. A scenario JSON file contains a timeline array of these messages, recorded from a real Google Cast device. Each entry in the timeline includes:

• time: The timestamp of the message (counted from bootstrap).
• ipcMessage: The stringified IPC message data sent from the sender.

{
  "timeline": [
    {
      "time": 5520,
      "ipcMessage": "{\"data\":{\\\"type\\\":\\\"visibilitychanged\\\"},\"namespace\":\"urn:x-cast:com.google.cast.system\",\"senderId\":\"SystemSender\"}"
    }
  ]
}

To record messages between a sender and a receiver app for use with the emulator, you must include the receiver-utils.min.js script in your CAF (Cast Application Framework) receiver app. This allows the CDE object to be available in the receiver's global scope for exporting scenarios.

<!-- Chromecast Device Emulator's Receiver Utilities -->
<script src="https://unpkg.com/chromecast-device-emulator/dist/receiver-utils.min.js"></script>
<!-- CAF -->
<script type="text/javascript" src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>

The CLI is ideal for local development. You can install the package globally to use the chromecast-device-emulator command or the cde shorthand. To start the emulator, provide a path to a pre-recorded scenario JSON file. The emulator will serve at port 8008 and establishes a new connection for each receiver app, allowing you to test multiple apps simultaneously.

# Install globally
$ npm install chromecast-device-emulator -g

# Start the emulator with a scenario file
$ chromecast-device-emulator start scenario.json

# Or using the shorthand
$ cde start scenario.json

After performing your desired user interactions (casting, pausing, volume changes, etc.) on a physical device with the receiver-utils script loaded, you can export the recorded data.

Open the Chrome DevTools console for your receiver app and run:

CDE.exportScenario()

Copy the resulting JSON output and save it as a .json file to use with the emulator.

// Run this in the Chrome DevTools console
CDE.exportScenario()

Once you have exported a scenario JSON file, you can use the CLI to start the emulator. This will load the scenario and establish a websocket server, making the emulator ready for receiver connections on your local machine.

$ chrome-device-emulator start scenario.json

To generate a scenario file, you must first intercept messages from a physical Google Cast device using the receiver-utils script.

Warning: This script performs hacky modifications to your receiver app at runtime. Remove this script tag from your production build.

<!-- 1. Add this script BEFORE the Google Cast SDKs -->
<script src="https://unpkg.com/chromecast-device-emulator/dist/receiver-utils.min.js"></script>

<!-- 2. Then load Cast APIs -->
<script>//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js</script>

After performing a series of actions (e.g., play, pause, seek) in your receiver app while the recorder is active, you can export the recorded scenario using Chrome DevTools remote debugging:

1. Open Google Chrome and navigate to chrome://inspect/#devices.
2. Locate your running receiver app and click the inspect link to open DevTools.
3. Switch to the Console tab.
4. Execute the command CDE.exportScenario();.
5. Copy the resulting JSON output (which follows the format {"timeline":[...]}) and save it to a .json file.

The emulator-devtool.js script is a utility entrypoint designed for use when running a Chromecast receiver outside of a physical Google Cast device, or when you need to record a scenario running on a physical device. Loading this script injects necessary polyfills and the scenario recorder into the receiver environment.

It performs two primary actions:

1. Loads device-polyfill to simulate the device environment.
2. Loads scenario-recorder to enable recording of IPC messages.

// Usage context: When running receiver out of Google Cast device
// or when you need to record a scenario running on a Google Cast device
require('./src/receiver-utils/index.js');

For integrating the emulator into test automation suites, install it as a development dependency. You can programmatically create an instance, load a scenario, start the server, and stop it.

var CastDeviceEmulator = require('chromecast-device-emulator');

// Create a new instance
var emulator = new CastDeviceEmulator();

// Load pre-recorded scenario
emulator.loadScenario(require('./scenario.json'));

// Startup the emulator
emulator.start();

// ... Do something ...

// Stop the emulator
emulator.stop();

When instantiating CastDeviceEmulator, you can pass an options object. Currently, the supported option is:

• silent (boolean): If true, the emulator will suppress log messages to the console during startup, connection, and message handling.

const emulator = new CastDeviceEmulator({
  silent: true
});

The CastDeviceEmulator class is the primary interface for emulating a Chromecast device. It works by starting a WebSocket server that listens on a specific port and path (defaulting to port 8008 and path /v2/ipc). When a Chromecast receiver connects, the emulator iterates through a pre-loaded scenario timeline and sends recorded IPC messages to the client at specified intervals using setTimeout.

const CastDeviceEmulator = require('chromecast-device-emulator');

const emulator = new CastDeviceEmulator({
  silent: false // Set to true to suppress logs
});

// 1. Load a scenario file containing a timeline of messages
emulator.loadScenario(require('./my-scenario.json'));

// 2. Start the emulator
emulator.start(() => {
  console.log('Emulator is running!');
});

// 3. Stop or close when finished
// emulator.stop();
// emulator.close();

The startEmulator function allows you to programmatically launch the Chromecast emulator by loading a pre-recorded scenario JSON file. It resolves the provided file path relative to the current working directory, loads the scenario, and starts the emulator instance.

Parameters:

• filepath (string): The path to the JSON scenario file. This path is resolved relative to process.cwd().
• cmd (any): An unused parameter in the current implementation, likely reserved for future CLI command extensions.

const { startEmulator } = require('chromecast-device-emulator/src/cli/app');

// Load a scenario file located at ./scenarios/my-scenario.json
startEmulator('./scenarios/my-scenario.json');