Media Monitor

A lightweight Windows application that monitors currently playing media across different apps and exposes the information via a WebSocket server.

This app started as a study on Windows C++ API's. The goal is to enhance this with other functionalities that requires audio/media API's in Windows.

Windows Defender False Positive

As a opensource and non-funded project I don't have funds to do code signing and due to that this project relies on Microsoft whitelisting protocol.

Under each release there will be an attached VirusTotal scan pointing to the current GitHub release executable.

An alternative for the false positives is to download the source code and build it locally.

AI usage

Code is not written by AI and it has been used as guidance and overall project management, like:

• Documentation
• Sample files

Features

• Monitors active media sessions on Windows using the Windows Runtime Media API
• Tracks media information including:
  • Title
  • Artist
  • Album
  • Duration
  • Playback state (playing/paused)
  • Thumbnail
• Exposes real-time media updates via WebSocket server
• Command-line interface for monitoring and control
• JSON-based configuration and data format

Running

Go to Releases and download the latest executable version available.

To run the application for now you can either double-click the executable it will open the default terminal and run. Or you can run it directly from the command-line, in that case the following command-line options are available:

• -l | --show-logs: Logs the last JSON broadcasted

WebSocket API

The application starts a WebSocket server that clients can connect to for receiving real-time media updates. Connect to the WebSocket server at: ws://localhost:7777 (default port can be configured in settings)

Real-time updates

When the client connects to the websocket it receives an initial session_init event. Whenever the progress position changes in the media the server will send a position_changed event. Whenever the track changes the server will send a track_changed event.

If you don't require real-time updates, check the "Querying for updates" section below.

{
  "event_name":"session_init | position_changed | track_changed",
  "payload":{
    "title":"Song Title",
    "artist":"Artist Name",
    "album":"Album Name",
    "app_id":"AppId",
    "app_name":"Friendly App Name",
    "duration": 0,
    "position": 0,
    "thumbnail":"base64 png image",
    "has_media":true,
    "is_playing":true
  }
}

Querying for updates

To optimize querying for updates you can update the settings to hide the query events being sent. Check the "Configuration" section.

current_media

Whenever you want the current media, instead of tracking the other messages, you can request sending the following payload:

{ "event_name": "current_media" }

The following json will be the response:

{
  "event_name":"current_media",
  "payload":{
    "title":"Song Title",
    "artist":"Artist Name",
    "album":"Album Name",
    "app_id":"AppId",
    "app_name":"Friendly App Name",
    "duration": 0,
    "position": 0,
    "thumbnail":"base64 png image",
    "has_media":true,
    "is_playing":true
  }
}

ping

If you need to avoid connection between your server and client idle for too long you can send ping requests.

{ "event_name": "ping" }

The following json will be the response:

{
  "event_name":"pong",
  "payload": null
}

Configuration

Settings can be configured by modifying the application's settings.ini file.

The default values for the settings are as follow:

[WebSocket]
Enabled=1
Port=7777

[Events]
TrackChanged=1
SessionChanged=1
PositionChanged=1

WebSocket

• Enabled = Enables or disables the websocket server (not very useful for now).
• Port = What port to bind the websocket server

Events

• TrackChanged = Enable/Disable the track_changed event when the track changes on the player
• SessionChanged = Enable/Disable the session_changed event when the player application changes (be aware that multiple players can be active at a time and can cause this event to trigger multiple times)
• PositionChanged = Enable/Disable the position_changed event triggered for every second the duration changes (be aware that depending on the player this can be skipped for few seconds or triggered milliseconds appart)

Samples

• sample.html = simple media tracking with progress bar & duration updates
• sample2.html = different style of progress bar & data updates with SVG manipulation
• sample3.html = different style of progress bar & data updates with SVG manipulation
• sample4.html = how to request current media information
• sample5.html = how to use thumbnails in html (base64 ready image)

Contributing

Requirements

• Windows 10 or later
• Visual Studio 2022 Build Tools or Visual Studio 2022
• CMake 3.30 or later
• vcpkg package manager

Dependencies

• Boost.System (for WebSocket server)
• nlohmann_json (for JSON handling)
• Windows Runtime APIs

Building

1. Clone the repository
2. Make sure vcpkg is properly set up and integrated with CMake
3. Build using CMake:

# Debug build
cmake --build build --config Debug

# Release build
cmake --build build --config Release

Running

After building, run the CLI executable:

./build/Debug/media_monitor_cli.exe    # Debug build
./build/Release/media_monitor_cli.exe  # Release build

Roadmap

no commitment, may change at any time

• Release workflow
• Sending commands to server
  • Ping
  • Get current media
• Settings (in-progress)
  • Port configuration
  • Websocket events toggle
  • Filters
  • Notifications
  • Tray (run in tray instead of command-line)
• Tests
• Custom Windows User Interface
• Audio Sessions detection
• Custom scripting (integrate with Node.JS(?) NAPI)
• Audio manipulation (play, stop, mute, volume)