<div align="center">

WLEDVideoSync

Cast video, images, or your screen to e131/artNet/DDP devices like WLED.

A Cross-Platform (Windows / Linux / macOS) Portable Application.

</div>

---

Key Features

• Versatile Streaming: Stream to e131, Art-Net, and DDP devices, including WLED.
• Multicast Support: Aggregate multiple devices into one large virtual matrix.
• Multiple Sources: Cast your desktop, a specific window, a screen area, images, videos, web URLs, and even YouTube content.
• Mobile Camera / Media Streaming: Use your phone as a wireless webcam / media source via a simple QR code scan (no third-party app needed).
• Text Overlays: Add custom text with multiple effects, fonts, and animations.
• Powerful UI: A modern web interface built with NiceGUI that can run as a native window, in a browser, or headlessly as a service.
• GIF Creation: Create GIFs from video segments and upload them directly to a WLED device, complete with a new preset.
• Full-Featured Scheduler: Automate your casts with recurring, one-shot, or custom-timed jobs.
• Coldtype Integration: a powerful Python library for typographic and graphic animation.
• Advanced Scripting: Extend functionality with a built-in Python editor and an external API for third-party integration.

---

Installation

Portable (Recommended)

1. Download: Grab the latest release for your OS from the Releases Page.
2. Extract:
   • Windows/Linux: Run the downloaded executable. It will extract a WLEDVideoSync folder.
   • macOS: Double-click the downloaded .zip or .tar.gz file to extract the .app bundle to WLEDVideoSync folder.
3. Run:
   • Windows/Linux: Open the extracted WLEDVideoSync folder and run the WLEDVideoSync-{OS} executable.
   • macOS: Before running, you must remove the quarantine attribute. Open a terminal and run:

     # Navigate to the folder where the app was extracted, e.g., Downloads
     cd ~/Downloads/WLEDVideoSync
     # Remove the attribute (replace x86_64 with arm64 if you have an Apple Silicon Mac)
     xattr -d com.apple.quarantine WLEDVideoSync-macOS_x86_64.app
     

     Afterward, you can double-click the WLEDVideoSync-macOS...app to run it.

   NOTA: on macOS, the first run will set all default settings depending on the platform

From Source (Manual)

1. Clone Repository: git clone https://github.com/zak-45/WLEDVideoSync.git
2. Install Dependencies: pip install -r requirements.txt (or pip3 on macOS/Linux).
3. Run Application: python WLEDVideoSync.py (or python3 on macOS/Linux).

---

Quick Start

1. Launch the Application: Start WLEDVideoSync.
2. Open Settings: In the left-side menu, click on Desktop Params or Media Params.
3. Configure Your Device:
   • Enter your WLED device's IP address in the IP field.
   • Check the WLED box to automatically detect the matrix size, or enter the Width and Height manually.
4. Start Casting:
   • Go to the Cast Center (main page).
   • Click the large Cast Icon for either Desktop or Media to start streaming!

---

User Guide

Installation

• Download the corresponding release to your OS : Get software -(Mac/Linux set +x on WLEDVideoSync app)

  • Double-click on it to extract WLEDVideoSync folder
  • Once extraction finished, you should see this screen:

  WLEDVideoSync folder can be copied and moved where you want, so keep organized.

• Go into and click on WLEDVideoSync-{OS}(exe/bin) to execute the main program.

  • If you are on Win/Mac system, this should open "native" windows

• On Linux, you should see the app into your default browser

All of this could be configured later, for the moment focus on default.

MAIN Interface

Header MENU

• MANAGE:
  • Screen to manage running DESKTOP / MEDIA Casts. From here you will be able to see all running casts spilt by type.

- available actions:  Cancel cast, to stop this cast
                      Snapshot, take a picture from running cast. Image will be stored into cast BUFFER
                      Stop Preview, close preview window
                      Start Preview, open preview window
                      Change IP address, stream to a different DDP device and if set to 127.0.0.1: suspend stream
                      Multicast effects, modify cast devices order in circular, reverse or random way

• DESKTOP PARAMS:
  • Manage DESKTOP parameters. Screen to manage DESKTOP parameters, see images into BUFFER and MULTICAST information.

 - **Params Info**:

    FPS: enter frame per second desired for the cast stream
    Scale width: cast x size in pixels  
    Scale height: cast y size in pixels
      These values should match Matrix 2D settings of your DDP device 
    
    wled: True or False, if true the DDP device act as WLED and app will try to retreive x,y values from it.
    IP: ip address of the DDP device

    Capture Methode: av or mss, av is the preferred one but mss should be necessary for macOS
                      mss do not run in wayland (linux)

    Input: input type to cast
        To cast entire desktop:
            'desktop': for Win OS
            ':0' or ':0.0' or other ... for Linux (should be the DISPLAY env)
        To cast only an area:
            'area' --> see SCREENAREA
        To cast a specific window content:
            'win=xxxxxxxxx'  where xxxxxx should be for Win the window title and for Linux window ID/or window title
        To cast from a 'SharedList':
            select 'SharedList', this will open a preview window with default image and waiting to receive images 
            from other processes (e.g: mobile / coldtype / text animation ...)
    Preview: True or False, if True a cast preview window will be displayed
    Format: 'gdigrab' for Win and 'x11grab' for Linux when want to cast Window/Desktop using av methode
    Codec: PyAV codec used, let it to 'libx264rgb' for now
    Screenarea / monitor number: select monitor number and click to SCREENAREA button to make area selection
                                (has some trouble on macOS)
    Output: give file name or rtsp, udp etc ... to stream input. For future use.-->*Protocol
    format: Pyav format
    Codec: Pyav codec 

    Capture Frame: True or False, True will capture frames from input
    Number: number of frames to capture, frames will be stored under BUFFER
    
    Multicast: True or False, if True and Matrix (x,y) = 1 then cast will stream to all IP into 'Cast Devices'
               for Matrix <> 1, this will split the cast stream into multiple images to create a Big virtual Matrix
               All DDP devices need to have the same 2D Matrix configuration                
    Matrix X: number of DDP devices on X axis
    Matrix Y: number of DDP devices on Y axis
                  e.g. WLED matrix 16x16 : 3(x) x 2(y)                    
                  ==> this require 6 devices to set into 'Cast Devices' list                         
                      (tuple of: device index(0...n) , IP address) 
                      This will create 6 images to send and provide big image of 3x16 leds for x and 2x16 for y

    Cast Devices: number and IP address of each DDP device. Number not yet managed
                  device order come from entry order 
    
    Protocol: e131 / artNet / ddp or other, if 'other' will use the 'Output' entry, let it to ddp for now

Main of these values can be saved into Preset to be reloaded

• MEDIA PARAMS:
  • Manage MEDIA parameters: Screen to manage MEDIA parameters, see images into BUFFER and MULTICAST information.

- Params info:

    FPS: enter frame per second desired for the cast stream
    Scale width: cast x size in pixels  
    Scale height: cast y size in pixels
      These values should match Matrix 2D settings of your DDP device 

    Input: input type to cast
           - 0, 1 or ...: this will cast your capture device number (e.g: USB Webcam)
           - enter full path of any of your media files, image or video
    Preview: True or False, if True a cast preview window will be displayed

    wled: True or False, if true the DDP device act as WLED and app will try to retreive x,y values from it.
    IP: ip address of the DDP device

    Capture Frame: True or False, True will capture frames from input
    Number: number of frames to capture, frames will be stored under BUFFER
    Seek to Frame N: start read at this position, do not work for real time media.
    
    Multicast: True or False, if True and Matrix (x,y) = 1 then cast will stream to all IP into 'Cast Devices'
               for Matrix <> 1, this will split the cast stream into multiple images to create a Big virtual Matrix
               All DDP devices need to have the same 2D Matrix configuration                
    Matrix X: number of DDP devices on X axis
    Matrix Y: number of DDP devices on Y axis
                  e.g. WLED matrix 16x16 : 3(x) x 2(y)                    
                  ==> this require 6 devices to set into 'Cast Devices' list