VLC Discord Rich Presence

Display your VLC media player activity on Discord with album artwork support

A lightweight integration that shows what you're currently playing in VLC Media Player as your Discord status, complete with album artwork, timestamps, and metadata.

✨ Features

• Real-time synchronization - Automatically updates your Discord status when playing media in VLC
• Album artwork display - Shows album covers using Catbox CDN hosting
• Accurate timestamps - Displays elapsed and remaining time
• Smart caching - Avoids re-uploading identical artwork
• Automatic cleanup - Clears Discord status when VLC stops playing
• Lightweight - Minimal resource usage with file-watching architecture

🚀 Quick Start

Prerequisites

• VLC Media Player
• Bun runtime
• PM2 (optional, for daemonization)
• Discord Desktop application

Installation

1. Clone the repository

   git clone https://github.com/Kisakay/VLC_Discord_RichPresence.git
   cd VLC_Discord_RichPresence

2. Install dependencies

   bun install

3. Configure the application

   Create a config.json file in the project root:

   {
     "CLIENT_ID": "your_discord_client_id",
     "NOW_PLAYING_PATH": "/path/to/vlc/now_playing.txt",
     "CATBOX_UPLOAD_URL": "https://catbox.moe/user/api.php",
     "HTTP_TIMEOUT": 10000,
     "DEFAULT_IMAGE": "https://your-default-image-url.com/vlc.png"
   }

4. Install the VLC extension

   Copy the Lua extension to your VLC extensions folder:

   • Linux: ~/.local/share/vlc/lua/extensions/
   • Windows: %APPDATA%\vlc\lua\extensions\
   • macOS: ~/Library/Application Support/org.videolan.vlc/lua/extensions/

   # Example for Linux
   mkdir -p ~/.local/share/vlc/lua/extensions/
   cp VLC_Discord_RichPresence.lua ~/.local/share/vlc/lua/extensions/

5. Enable the extension in VLC

   • Open VLC Media Player
   • Go to View → VLC_Discord_RichPresence
   • The extension is now active

Running the Application

Development mode:

bun run index.ts

Production with PM2:

pm2 start index.ts --interpreter bun --name vlc-discord-rpc
pm2 save
pm2 startup

📁 Project Structure

VLC_Discord_RichPresence/
├── index.ts                    # Main entry point
├── config.json                 # Configuration file
├── package.json                # Dependencies
├── VLC_Discord_RichPresence.lua # VLC extension
├── src/
│   ├── RPCManager.ts           # Discord RPC handler
│   ├── constants.ts            # Configuration constants
│   ├── types/
│   │   └── types.ts            # TypeScript interfaces
│   └── utils/
│       ├── readNowPlaying.ts   # File parser
│       └── statesEqual.ts      # State comparison
└── assets/
    └── demo.png                # Demo screenshot

🔧 How It Works

1. VLC Extension - The Lua script monitors VLC playback and writes metadata to a text file
2. File Watcher - The Node.js application watches this file for changes
3. Artwork Upload - Album artwork is encoded to base64, then uploaded to Catbox CDN
4. Discord RPC - Metadata is formatted and sent to Discord via the Rich Presence API

Data Flow

VLC Media Player
    ↓ (Lua Extension)
now_playing.txt
    ↓ (File Watcher)
Node.js Application
    ↓ (Upload artwork)
Catbox CDN
    ↓ (Update status)
Discord Rich Presence

🎵 Supported Metadata

• Title - Track name
• Artist - Performer/composer
• Album - Album name
• Artwork - Album cover (uploaded to Catbox)
• Duration - Total track length
• Progress - Current playback position

⚙️ Configuration Options

Option	Description	Default
CLIENT_ID	Discord application client ID	Required
NOW_PLAYING_PATH	Path to VLC output file	OS-dependent
CATBOX_UPLOAD_URL	Artwork upload endpoint	https://catbox.moe/user/api.php
HTTP_TIMEOUT	Upload timeout in milliseconds	10000
DEFAULT_IMAGE	Fallback image URL	VLC logo

Getting a Discord Client ID

1. Go to Discord Developer Portal
2. Click "New Application"
3. Give it a name (e.g., "VLC Media Player")
4. Copy the "Application ID" from the General Information page
5. Use this as your CLIENT_ID in config.json

🐛 Troubleshooting

Discord status not updating:

• Ensure Discord Desktop is running (not web version)
• Verify the VLC extension is enabled
• Check that now_playing.txt is being written to

Artwork not displaying:

• Verify the Catbox upload URL is accessible
• Check file permissions on artwork files
• Look for upload errors in the console output

VLC extension not appearing:

• Confirm the .lua file is in the correct extensions directory
• Restart VLC after installing the extension
• Check VLC logs for Lua errors

🧪 Tested On

• NixOS - Primary development platform
• Arch Linux - Confirmed working
• Windows 10/11 - Community tested
• macOS - Community tested

📝 License

This project is open source. See the repository for license details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🙏 Acknowledgments

• VLC Media Player - The best media player
• Discord RPC - Rich Presence API
• Catbox.moe - Free file hosting service
• @xhayper/discord-rpc - Discord RPC library

📧 Contact

Kisakay - GitHub

Project Link: https://github.com/Kisakay/VLC_Discord_RichPresence

---

⭐ If you find this project useful, please consider giving it a star on GitHub!