gst-projectm

GStreamer plugin utilizing the ProjectM library.

Report Bug · Request Feature

Table of Contents

1. Getting Started
2. Easy Audio to Video Conversion
   • Using Docker Container
   • Conversion Examples
   • Customizing Visualizations
3. Manual Usage
4. Contributing
5. License
6. Support
7. Contact

Getting Started

The documentation has been organized into distinct files, each dedicated to a specific platform. Within each file, you'll find detailed instructions covering the setup of prerequisites, the building process, installation steps, and guidance on utilizing the plugin on the respective platform.

• Linux
• OSX
• Windows

Once the plugin has been installed, you can use it something like this:

gst-launch pipewiresrc ! queue ! audioconvert ! projectm preset=/usr/local/share/projectM/presets preset-duration=5 ! video/x-raw,width=2048,height=1440,framerate=60/1 ! videoconvert ! xvimagesink sync=false

Or to convert an audio file to video:

filesrc location=input.mp3 ! decodebin name=dec \
    decodebin ! tee name=t \
      t. ! queue ! audioconvert ! audioresample ! \
            capsfilter caps="audio/x-raw, format=F32LE, channels=2, rate=44100" ! avenc_aac bitrate=256000 ! queue ! mux. \
      t. ! queue ! audioconvert ! projectm preset=/usr/local/share/projectM/presets preset-duration=3 mesh-size=1024,576 ! \
            identity sync=false ! videoconvert ! videorate ! video/x-raw,framerate=60/1,width=3840,height=2160 ! \
            x264enc bitrate=35000 key-int-max=300 speed-preset=veryslow ! video/x-h264,stream-format=avc,alignment=au ! queue ! mux. \
  mp4mux name=mux ! filesink location=render.mp4;

Available options

gst-inspect projectm

(back to top)

Demo Videos (4K)

https://www.youtube.com/watch?v=fI3BMiVDQgU&list=PLFLkbObX4o6TK1jGL6pm1wMwvq2FXnpYJ&index=7

Easy Audio to Video Conversion

We provide a simple way to convert audio files to video with ProjectM visualizations using Docker. This method requires no manual installation of dependencies, as everything is packaged in a Docker container.

Docker Container

The included Docker container has:

• ProjectM library and presets
• GStreamer with all necessary plugins
• The gst-projectm plugin compiled and ready to use
• GPU acceleration support (NVIDIA, AMD, or Intel)

Prerequisites

• Docker installed on your system
• For GPU acceleration:
  • NVIDIA GPUs: NVIDIA Container Toolkit
  • AMD/Intel GPUs: No additional installation required

Quick Start

1. Clone this repository:

   git clone https://github.com/projectM-visualizer/gst-projectm.git
   cd gst-projectm

2. Convert an audio file to video:

   ./projectm-convert -i your-audio-file.mp3 -o output-video.mp4

The first run will build the Docker container automatically. It will take a good while, so be patient. Once built, it will be cached for future runs.

Note that running the conversion can take hours depending on the length of the audio file and the selected settings.

Conversion Examples

Basic Conversion

Convert an MP3 to a 1080p MP4 with default settings:

./projectm-convert -i my-song.mp3 -o my-visualization.mp4

4K Resolution

Create a 4K video with higher bitrate:

./projectm-convert -i my-song.mp3 -o my-visualization-4k.mp4 --video-size 3840x2160 -b 16000

High Quality Render

For creating high quality videos (slower encoding):

./projectm-convert -i my-song.mp3 -o my-visualization-hq.mp4 --speed veryslow --mesh 2048x1152

Quick Test Run

For quick testing (lower quality but faster encoding):

./projectm-convert -i my-song.mp3 -o my-visualization-test.mp4 --speed ultrafast --video-size 1280x720

Customizing Visualizations

The conversion script supports customizing various aspects of the visualization:

Option	Description	Default
-d, --duration SEC	Time in seconds between preset transitions	6
--mesh WxH	Mesh size for visualization calculations	1024x576
--video-size WxH	Output video resolution	1920x1080
-r, --framerate FPS	Output video frame rate	60
-b, --bitrate KBPS	Output video bitrate in kbps	8000
--speed PRESET	x264 encoding speed preset (ultrafast to veryslow)	medium
-p, --preset DIR	Path to custom presets directory	Default presets

Using Custom Presets

If you have your own ProjectM preset files:

./projectm-convert -i my-song.mp3 -o my-visualization.mp4 -p /path/to/your/presets

(back to top)

Manual Usage

Once the plugin has been installed, you can use it something like this:

gst-launch pipewiresrc ! queue ! audioconvert ! projectm preset=/usr/local/share/projectM/presets preset-duration=5 ! video/x-raw,width=2048,height=1440,framerate=60/1 ! videoconvert ! xvimagesink sync=false

Or to convert an audio file to video:

gst-launch-1.0 -e \
  filesrc location=input.mp3  ! \
    decodebin ! tee name=t \
      t. ! queue ! audioconvert ! audioresample ! \
            capsfilter caps="audio/x-raw, format=F32LE, channels=2, rate=44100" ! avenc_aac bitrate=320000 ! queue ! mux. \
      t. ! queue ! audioconvert ! projectm preset=/usr/local/share/projectM/presets texture-dir=/usr/local/share/projectM/textures preset-duration=6 mesh-size=1024,576 ! \
            identity sync=false ! videoconvert ! videorate ! video/x-raw,framerate=60/1,width=3840,height=2160 ! \
            x264enc bitrate=50000 key-int-max=200 speed-preset=veryslow ! video/x-h264,stream-format=avc,alignment=au ! queue ! mux. \
    mp4mux name=mux ! filesink location=output.mp4

You may need to adjust some elements which may or may not be present in your GStreamer installation, such as x264enc, avenc_aac, etc.

Available options:

gst-inspect projectm

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
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

(back to top)

License

Distributed under the LGPL-2.1 license. See LICENSE for more information.

(back to top)

Support

(back to top)

Contact

Blaquewithaq (Discord: SoFloppy#1289) - @anomievision - [email protected]

Mischa (Discord: mish) - @revmischa

(back to top)