Yamaha MusicCast™ v0.2.2 MusicCast.Network.Entity

A module for managing MusicCast™ enabled devices.

A network entity is automatically started when a MusicCast enabled device is discovered. See the MusicCast.UPnP.SSDPClient for implementation details. Once started, the entity process is available to the network registry via it MusicCast device ID:

iex> pid = MusicCast.whereis("00A0DEDCF73E")
#PID<0.200.0>

Synchronization

Each entity process keeps it state synchronized with the device it is paired with. This task is acomplished by the MusicCast.Network.EventDispatcher process which forwards incoming YXC unicast messages to the affected entity processes.

In order to receive UPnP A/V notification from MusicCast™ devices via UPnP A/V, you must forward the MusicCast.UPnP.Plug.EventDispatcher plug in your HTTP stack and configure your application accordingly.

YXC & UPnP

Extended Control or “YXC” is Yamaha’s communication protocol sent over Ethernet and Wi-Fi to control MusicCast™ devices. Each entity provides a set of functions for interacting with a device.

See MusicCast.ExtendedControl for more details.

On top of the commands provided by YXC, entities support the UPnP A/V Transport protocol. Functions such as playback_load/3 and playback_load_queue/2 provide a way to load streamable content via an URL.

Gapless playback can be achieved with a combination of playback_load/3 and playback_load_next/3. The latter basically tells the rendering devices which source to play next.

To play multiple items, consider using playback_load_queue/2, it handles “previous” and “next” commands automatically, ensures gapless playback and supports “repeat” and “shuffle” modes.

See MusicCast.UPnP.AVTransport for more details.

Summary

Types

ip_address()

lookup_key()

lookup_query()

playback()

status()

t()

Functions

__lookup__(pid, keys \\ :all)

Returns the state value(s) for the given lookup key(s)

decrease_volume(pid, step \\ 10)

Decreases the volume by step

increase_volume(pid, step \\ 10)

Increases the volume by step

mute(pid)

Mutes the volume

playback_load(pid, url, meta \\ nil)

Loads the given URL and immediately begins playback

playback_load_next(pid, url, meta \\ nil)

Sets the next URL to load for gapless playback

playback_load_queue(pid, items)

Loads the given list of items and immediately begins playback

playback_next(pid)

Plays the next track in the playback queue

playback_pause(pid)

Pauses playback of the current track

playback_play(pid)

Begins playback of the current track

playback_previous(pid)

Plays the previous track in the playback queue

playback_stop(pid)

Stops playback

set_input(pid, input)

Selects the given input

set_power(pid, power)

Sets the power status to “on” or “standby”

set_volume(pid, volume)

Sets the volume to the given volume

start_link(addr, upnp_desc, options \\ [])

Starts an entity as part of a supervision tree

stop(pid, reason \\ :normal, timeout \\ :infinity)

Stops the entity process

toggle_play_pause(pid)

Toggles playback state from “play” to “pause” and vice versa

toggle_repeat(pid)

Toggles repeat settings

toggle_shuffle(pid)

Toggles repeat settings

unmute(pid)

Unmutes the volume

Types

ip_address()

ip_address() :: {0..255, 0..255, 0..255, 0..255}

lookup_key()

lookup_key ::
  :available_inputs |
  :device_id |
  :host |
  :network_name |
  :playback |
  :playback_queue |
  :status |
  :upnp |
  :upnp_service |
  :upnp_session_id

lookup_query()

lookup_query() :: :all | [lookup_key] | lookup_key

playback()

playback() :: %{album: String.t, albumart_url: String.t, artist: String.t, input: String.t, play_time: Integer.t, playback: String.t, repeat: String.t, shuffle: String.t, total_time: Integer.t, track: String.t}

status()

status() :: %{balance: Integer.t, bass_extension: boolean, direct: boolean, disable_flags: Integer.t, distribution_enable: boolean, enhancer: boolean, equalizer: %{high: Integer.t, low: Integer.t, mid: Integer.t, mode: String.t}, input: String.t, link_audio_delay: String.t, link_control: String.t, max_volume: Integer.t, mute: boolean, power: String.t, sleep: Integer.t, subwoofer_volume: Integer.t, volume: Integer.t}

t()

t() :: %MusicCast.Network.Entity{available_inputs: [String.t], device_id: String.t, host: String.t, network_name: String.t, playback: playback, playback_queue: %{media_url: String.t, items: [MusicCast.UPnP.AVMusicTrack.didl_item]}, status: status, upnp: MusicCast.UPnP.AVTransport.t, upnp_service: MusicCast.UPnP.Service.t, upnp_session_id: String.t}

Functions

__lookup__(pid, keys \\ :all)

__lookup__(pid, lookup_query) :: any

Returns the state value(s) for the given lookup key(s).

If you pass :all, this function will return the full state of the entity.

iex> MusicCast.Network.Entity.__lookup__(pid, :all)
%MusicCast.Network.Entity{...}

If you prefer to query a subset of the entity’s state, you can pass any number of lookup_key/0:

iex> MusicCast.Network.Entity.__lookup__(pid, [:host, :network_name])
["192.168.0.63", "Schlafzimmer"]

decrease_volume(pid, step \\ 10)

decrease_volume(pid, Integer.t) :: :ok | {:error, term}

Decreases the volume by step.

increase_volume(pid, step \\ 10)

increase_volume(pid, Integer.t) :: :ok | {:error, term}

Increases the volume by step.

mute(pid)

mute(pid) :: :ok | {:error, term}

Mutes the volume.

playback_load(pid, url, meta \\ nil)

playback_load(pid, String.t, Enum.t) :: :ok | {:error, term}

Loads the given URL and immediately begins playback.

If given, meta must conform to MusicCast.UPnP.AVMusicTrack.t/0.

playback_load_next(pid, url, meta \\ nil)

playback_load_next(pid, String.t, Enum.t) ::
  :ok |
  {:error, term}

Sets the next URL to load for gapless playback.

If given, meta must conform to MusicCast.UPnP.AVMusicTrack.t/0.

playback_load_queue(pid, items)

playback_load_queue(pid, [Enum.t]) :: :ok | {:error, term}

Loads the given list of items and immediately begins playback.

All given items must conform to MusicCast.UPnP.AVMusicTrack.didl_item/0.

playback_next(pid)

playback_next(pid) :: :ok | {:error, term}

Plays the next track in the playback queue.

playback_pause(pid)

playback_pause(pid) :: :ok | {:error, term}

Pauses playback of the current track.

playback_play(pid)

playback_play(pid) :: :ok | {:error, term}

Begins playback of the current track.

playback_previous(pid)

playback_previous(pid) :: :ok | {:error, term}

Plays the previous track in the playback queue.

playback_stop(pid)

playback_stop(pid) :: :ok | {:error, term}

Stops playback.

set_input(pid, input)

set_input(pid, String.t) :: :ok | {:error, term}

Selects the given input.

To get a list of available inputs from a specific device, see __lookup__/2.

set_power(pid, power)

set_power(pid, String.t) :: :ok | {:error, term}

Sets the power status to “on” or “standby”.

set_volume(pid, volume)

set_volume(pid, Integer.t) :: :ok | {:error, term}

Sets the volume to the given volume.

start_link(addr, upnp_desc, options \\ [])

start_link(ip_address, MusicCast.UPnP.Service.t, Keyword.t) :: GenServer.on_start

Starts an entity as part of a supervision tree.

stop(pid, reason \\ :normal, timeout \\ :infinity)

stop(pid, term, timeout) :: :ok

Stops the entity process.

toggle_play_pause(pid)

toggle_play_pause(pid) :: :ok | {:error, term}

Toggles playback state from “play” to “pause” and vice versa.

toggle_repeat(pid)

toggle_repeat(pid) :: :ok | {:error, term}

Toggles repeat settings.

toggle_shuffle(pid)

toggle_shuffle(pid) :: :ok | {:error, term}

Toggles repeat settings.

unmute(pid)

unmute(pid) :: :ok | {:error, term}

Unmutes the volume.