VLC Media Player

Turn a VLC instance into a GEM audio source. GEM talks to VLC over its built-in HTTP control interface: it drives playback transport and volume, reads back what's playing, and parses VLC's media library into a browsable Artists / Albums / Tracks / Playlists index so a user can pick music from a touchpanel. One VLC instance is one GEM device.

VLC is software, not a piece of rack gear — it runs on a media PC, an audio server, or a small always-on box wired into the room's amplifier or matrix input. The typical install is a headless machine playing a shared music library, exposed to rooms as a selectable AV source.

How it connects

• The connection is plain HTTP to the machine's IP on the VLC HTTP port (default 9090, set with HTTP Port). Responses come back as JSON (playback/status) or XML (the media library); the driver parses them for you.
• VLC's HTTP interface uses a single password, no username. GEM puts that password in the request URL, so anyone who can sniff the control LAN can read it — keep the media PC and GEM on a trusted or management network.
• Once connected, GEM polls VLC for the current track on the Now-Playing Poll interval (default 3000 ms) and writes the title, artist, album, transport state, and shuffle/repeat flags back onto the device so panels and triggers stay current.

Prerequisites

• A machine running VLC with the HTTP interface enabled and a password set. VLC does not expose the HTTP interface by default — you launch it (or configure it) for HTTP control, for example:

  vlc --intf http --http-host 0.0.0.0 --http-port 9090 --http-password <password>

  On a headless server this is usually set up as a service so VLC comes back after a reboot.

• VLC's Media Library enabled, pointed at the music folder, with playlist behavior set to "expand" in VLC's preferences. This is what makes VLC publish the artist / album / track / playlist tree that GEM browses — without it, browse and search return nothing.

• A static IP or DHCP reservation on the machine — the device row is pinned to one address, so a lease change would silently break control.

• Network access to the HTTP port from the GEM server to the machine.

Setup

Open Devices

1. On the media PC, launch VLC with the HTTP interface and a password (see Prerequisites), and confirm you can reach http://<ip>:9090/ from another machine on the network.
2. In VLC's preferences, enable the Media Library, point it at the music folder, and set the playlist behavior to expand so artists/albums/tracks are exposed.
3. In GEM, go to System → Devices → Add Device and choose the VLC Media Player driver. Give it a name, save, and enable it.
4. Fill in the connection fields:
   • VLC Host IP — the LAN address of the machine running VLC.
   • HTTP Password — the password you set on VLC's HTTP interface (stored encrypted).
   • HTTP Port — leave at 9090 unless you started VLC on a different port.
5. (Optional) Set Media Library Path to the exact filesystem path VLC scanned for media (default /media/music). GEM uses this to build the play command for a whole artist, album, or playlist, so it must match VLC's real folder layout — see The media library below.
6. Save. On connect the driver parses the library and starts the now-playing poll. VLC is now controllable from macros, the AI assistant, an AV source panel, and any widget bound to its state.

Using VLC as an on-screen source

This is the primary way VLC is used: as a selectable source that opens a full music browser on the touchpanel.

1. Open AV Sources and add a source.
2. Set Device to this VLC device.
3. Set Component to mp3 — the music browser panel.
4. Mark it Global source if every room should be able to pick it, and save.

When a user selects that source in a room, GEM draws the mp3 panel:

• A Media navigator with Playlists, Artists, Albums, and Now Playing.
• Tapping an artist drills into its albums; tapping an album or a playlist lists its tracks; tapping a track plays it immediately.
• Bottom controls: Play and Add-to-queue (act on the item currently open), a Search button that opens an on-screen keyboard to filter the current list, and a Back button.
• Now Playing shows the current title, artist, album, and cover art (fetched live from VLC).

VLC has no per-room concept

Each VLC device is a single playback endpoint — the source doesn't take an address and doesn't split into per-room zones. If several rooms select the VLC source, they all control the same VLC instance. For independent per-room music, run a VLC instance per room, each as its own device and source.

Using VLC as a room's volume / output

If the VLC machine is wired to a room's amplifier and is that room's audio output, you can bind it as an AV zone's Volume Device so the room gets a volume slider and transport control:

1. Open AV Zones and pick (or create) the zone for that room.
2. Set its Volume Device to this VLC device. Volume and transport commands sent to the zone now address VLC.

No mute

This driver does not implement a mute command, and mute cannot be emulated from one (there is no mute_on / mute_off to fall back to). A mute button on a zone whose Volume Device is VLC does nothing. Use volume to set the level, or pause to stop audio. VLC also has no power on/off — it is an always-running player; use play / pause / stop for transport.

The media library

GEM builds its browse index by reading VLC's exported library tree once on connect, then keeps it in memory for fast browsing and search.

• Re-scan after changes. If you add or remove music, or the browse lists look empty or stale, run the update_media_library command on the device to re-read VLC's library. You can also restart VLC — its export occasionally omits an artist or album block during a scan.
• Media Library Path matters for folder play. Playing a whole artist, album, or playlist tells VLC to open the corresponding folder under the Media Library Path, so that path must match where VLC's files actually live. Playing an individual track uses the file location VLC itself reported, so single-track play works regardless of this setting.
• Playlists live in a Playlists subfolder. Playlist playback opens <Media Library Path>/Playlists/<playlist file>, so exported playlists must sit in a Playlists folder under the library path to play as a whole.

Attributes

Device — required

Attribute	Type	Description
ip	string	VLC Host IP — LAN address of the machine running VLC.
password	string	HTTP Password — the password set on VLC's HTTP interface. Stored encrypted.

Device — optional

Attribute	Type	Default	Description
port	int	9090	HTTP Port VLC's HTTP interface is listening on.
media_library_path	string	/media/music	Filesystem path VLC scanned for media. Used to build play commands for a whole artist/album/playlist.
now_playing_interval	int	3000	Now-Playing Poll (ms) — how often GEM asks VLC what's playing.
search_result_limit	int	20	Maximum results returned by a search_media call.

Read-only now-playing state

The driver writes these onto the device as VLC plays. They are stable names to bind widgets and build Triggers against — you don't set them by hand.

Attribute	Type	Meaning
title	string	Current track title.
artist	string	Current track artist.
album	string	Current track album.
device_state	string	Transport state reported by VLC (e.g. playing, paused, stopped).
shuffle	bool	Whether VLC's random mode is on.
repeat	bool	Whether repeat is on.

Commands

Set these from a macro, a control, or the AI assistant. Argument names below are the exact strings you put in a macro step's arguments.

Transport

Command	Args	Description
play	—	Resume / start playback.
pause	—	Pause.
stop	—	Stop.
next	—	Next track.
previous	—	Previous track.
scan_forward	—	Seek forward within the current track.
scan_reverse	—	Seek backward within the current track.
shuffle	—	Toggle shuffle (VLC's random mode).
repeat	—	Toggle repeat.
clear_queue	—	Empty the play queue.

Volume

Command	Args	Description
volume	volume	Set VLC's output volume to a percentage, 0–100.

Browse, search, and play from the library

Command	Args	Description
browse_media	entity, artist, album	List library items. entity is artist, album, playlist, or track. Narrow tracks with artist + album, or playlist; narrow albums with artist.
search_media	entity, query	Search the library. entity is artist, album, playlist, track, or all (searches track name + artist + album). Capped at Search Result Limit.
play_media	entity, name, id	Clear the queue and play the chosen item (artist, album, playlist, or track).
queue_media	entity, artist, album, playlist, track	Add the chosen item to the queue without clearing it.
update_media_library	—	Re-read VLC's library into GEM's browse index. Run after library changes.

Status

Command	Args	Description
get_status	—	Read the current transport state and now-playing metadata on demand.
get_current_queue	—	Return VLC's current play queue.
get_artwork	—	Return the current track's cover art (as a data image, used by the Now Playing view).

The mp3 source panel above drives browse_media, search_media, play_media, queue_media, and get_artwork for you — you rarely call these by hand except when scripting playback in a macro (for example, a "goodnight" macro that plays a specific playlist).

Behavior and limitations

• No mute and no power. VLC exposes neither a mute nor a power command — see the note under Using VLC as a room's volume / output. Drive transport with play / pause / stop.
• The library must be enabled and expanded in VLC. Browse and search read VLC's exported library tree; if the Media Library is off, or playlist behavior isn't set to "expand", the lists come back empty even though transport still works.
• Folder play depends on Media Library Path. Whole-artist / album / playlist playback opens a folder path built from Media Library Path; a mismatch here is the usual cause of "a single track plays but an album won't."
• One instance, one endpoint. VLC has no rooms of its own. Multiple rooms on the same VLC source share one playback stream; run one VLC per room for independent audio.

Troubleshooting

Symptom	Check
Device shows disconnected.	Confirm http://<ip>:9090/ answers from the GEM host's network, that VLC was launched with the HTTP interface, and that the HTTP Password matches. A wrong IP after a DHCP lease change is common — give the machine a reservation.
Browse / search lists are empty.	Enable VLC's Media Library, point it at the music folder, and set playlist behavior to expand, then run update_media_library (or restart VLC).
A single track plays but a whole album or playlist doesn't.	Media Library Path must match VLC's real folder layout, and playlists must sit in a Playlists subfolder under it.
Now-playing metadata never updates.	Confirm the device is enabled and reachable; the poll runs on Now-Playing Poll (ms). Lower it for snappier updates, raise it to reduce traffic.
A room's mute button does nothing.	Expected — VLC has no mute. Use the volume slider or pause.
Cover art doesn't show.	VLC only serves art for tracks that carry embedded artwork; the panel falls back to a generic music icon otherwise.

Related

• AV Sources — set the Component (mp3) and Device for the VLC source panel.
• AV Zones — bind VLC as a zone's Volume Device.
• Channels — how on-screen browsers and favorites are stored.
• Multiview — show a VLC source alongside others on one screen.
• Sonos and Denon HEOS — other browsable whole-home audio sources.
• Attributes — where you set Media Library Path and the poll interval.
• Commands — running and scripting the commands above.
• Devices — adding and configuring devices.
• Triggers — fire automations off VLC's device_state / title.