{"id":47948842,"url":"https://github.com/openpeeps/groovebox","last_synced_at":"2026-04-04T08:55:11.840Z","repository":{"id":340323952,"uuid":"1111766955","full_name":"openpeeps/groovebox","owner":"openpeeps","description":"📦 Badass Live Streaming Straight from Your Disk! ⚡️ Built-in RTMP Client \u0026 Server + Streaming client to 🧊 Icecast-compatible servers ","archived":false,"fork":false,"pushed_at":"2026-02-27T12:33:19.000Z","size":120,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-04T08:55:10.266Z","etag":null,"topics":["audio-streaming","icecast","libevent","media-streaming","mp3","music","music-streaming","nim","nim-lang","ogg","openpeeps","radio-station","rtmp-client","rtmp-server","video-streaming","video-streaming-server"],"latest_commit_sha":null,"homepage":"","language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openpeeps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-07T15:45:38.000Z","updated_at":"2026-02-27T12:33:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/openpeeps/groovebox","commit_stats":null,"previous_names":["openpeeps/groovebox"],"tags_count":0,"template":false,"template_full_name":"openpeeps/pistachio","purl":"pkg:github/openpeeps/groovebox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openpeeps%2Fgroovebox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openpeeps%2Fgroovebox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openpeeps%2Fgroovebox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openpeeps%2Fgroovebox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openpeeps","download_url":"https://codeload.github.com/openpeeps/groovebox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openpeeps%2Fgroovebox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31393781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-streaming","icecast","libevent","media-streaming","mp3","music","music-streaming","nim","nim-lang","ogg","openpeeps","radio-station","rtmp-client","rtmp-server","video-streaming","video-streaming-server"],"created_at":"2026-04-04T08:55:10.636Z","updated_at":"2026-04-04T08:55:11.829Z","avatar_url":"https://github.com/openpeeps.png","language":"Nim","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/openpeeps/groovebox/blob/main/.github/groovebox_logo.png\" width=\"90px\"\u003e\u003cbr\u003e\n  Groovebox 📦 Badass CLI app for streaming to Twitch, Youtube,\u003cbr\u003eany RTMP servers and 🧊 Icecast-compatible servers\u003cbr\u003e\u003cbr\u003e\n  Fast \u0026bullet; Lightweight \u0026bullet; Compiled \u0026bullet; 👑 Written in Nim language\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ccode\u003enimble install groovebox\u003c/code\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/\"\u003eAPI reference\u003c/a\u003e\u003cbr\u003e\n  \u003cimg src=\"https://github.com/openpeeps/groovebox/workflows/test/badge.svg\" alt=\"Github Actions\"\u003e  \u003cimg src=\"https://github.com/openpeeps/groovebox/workflows/docs/badge.svg\" alt=\"Github Actions\"\u003e\n\u003c/p\u003e\n\n\u003e [!NOTE]\n\u003e Groovebox is still in active development. Expect bugs and incomplete features!\n\n## About\n**Groovebox is a lightweight CLI application for live streaming pre-recorded playlists of media to YouTube, Twitch and other RTMP (Real-Time Messaging Protocol) servers**. Comes with a built-in RTMP server implementation that can be used to receive and redistribute streams to other clients.\n\nAlso, with Groovebox you can stream music to Icecast-compatible servers! It is designed to be **fast**, **memory-efficient**, and **easy to use**, making it ideal for streaming sessions and internet radio stations.\n\n### How it works?\nIt streams files (one-by-one) from playlists; it does not capture live camera or microphone input. Also, **Groovebox does not require any GPU acceleration as it does not perform any video encoding or decoding itself.** Still, you can use the predefined CLI commands to convert media files to formats suitable for streaming using ffmpeg.\n\nGroovebox media streams are sourced from local audio files (MP3, OGG Vorbis, OGG Opus, AAC, and more) from a specific `txt` playlist file and streamed directly to an **Icecast2-compatible** server or **RTMP servers** with **zero-copy audio/video streaming**, allowing for efficient streaming of large media files without consuming excessive system resources.\n\n## 😍 Key Features\n- 🔥 Compiled, **extremely lightweight**, and **super fast**\n- 🎵 Supports **MP3, OGG Vorbis, OGG Opus, AAC**, and more via external encoders\n- 📸 RTMP (Real-Time Messaging Protocol) support for future expansion\n- 👌 Icecast Client compatible with **Icecast2 servers**\n- 📀 **Zero-copy Media Streaming** for maximum performance and minimal memory usage\n- 🔀 Shuffle tracks in playlist\n- Works on **Linux** and **macOS**\n- 🎩 Open Source | AGPLv3 License\n- 👑 Written in Nim language | Made by Humans from OpenPeeps\n\n\u003e [!NOTE]\n\u003e Groovebox does not provide an encoder/decoder (codec) implementation. It is intended to be used for streaming pre-encoded audio/video via tools such as ffmpeg.\n\n\n## Install\nUsing [Nimble](https://nim-lang.org/install.html), the package manager for Nim:\n```bash\nnimble install groovebox\n# or install from GitHub\nnimble install https://github.com/openpeeps/groovebox\n```\n\nOtherwise, get the latest release from the [Releases](https://github.com/openpeeps/groovebox/releases) page (soon).\n\n## Usage\nAfter installing Groovebox, you can run the `groovebox -h` command in your terminal to see the available options and commands.\n\n```\n$ groovebox -h\n\n__________                              ___________              \n /  _____/______  ____   _______  __ ____\\______   \\ _______  ___\n/   \\  __\\_  __ \\/  _ \\ /  _ \\  \\/ // __ \\|    |  _//  _ \\  \\/  /\n\\    \\_\\  \\  | \\(  \u003c_\u003e |  \u003c_\u003e )   /\\  ___/|    |   (  \u003c_\u003e \u003e    \u003c \n \\______  /__|   \\____/ \\____/ \\_/  \\___  \u003e______  /\\____/__/\\_ \\\n        \\/                              \\/       \\/            \\/\nLive stream pre-recorded music to Twitch, Yotube and Icecast servers\n  (c) George Lemon | AGPL-3.0-or-later License  \n  Build Version: 0.1.0\n  \n  init \u003cconfig:path\u003e                    Initialize a new Groovebox Configuration file\nStreaming\n  icecast \u003cconfig:path\u003e                 Stream media to a Icecast server\n  rtmp ▲                                \n    server \u003cconfig:path\u003e             Start a local RTMP server to receive streams\n    stream \u003cconfig:path\u003e             Stream media to a RTMP server\nMedia Tools\n  flv \u003cin:path\u003e \u003cout:filepath\u003e          Convert media to FLV format for RTMP streaming\n  aac \u003cin:path\u003e \u003cout:filepath\u003e          Convert audio to AAC format for RTMP streaming\n    --kbs\n  ogg \u003cin:path\u003e \u003cout:filepath\u003e          Convert audio to OGG format for Icecast streaming\n    --kbs\n```\n\n## Prepare media for streaming\nUse the built-in Groovebox commands to prepare your media files for streaming. For RTMP streaming you can use the `flv` command to convert your video files to FLV format, and the `aac` command to convert your audio files to AAC format. For Icecast streaming, you can use the `ogg` command to convert your audio files to OGG format.\n\nNote: Groovebox is using the `ffmpeg` under the hood to convert audio/video files, so you need to have `ffmpeg` installed on your system and available in your PATH for these commands to work.\n\n## Groovebox Configuration\nGroovebox uses a YAML configuration file to specify the streaming settings, including the RTMP server URL, Stream Key, and playlist paths. You can create a new configuration file using the `groovebox init` command, or you can create it manually. The configuration file should be named `groovebox.config.yaml` and placed in the root of streaming project.\n\n## Icecast Streaming\nTo stream to an Icecast-compatible server, you will need to provide the server address, port, mount point, and the playlist file in the `groovebox.config.yaml` file:\n```yaml\ntype: icecast\nicecast:\n  connection:\n    address: localhost\n    port: 8000\n    mountPoint: \"/stream\"\n    playlists:\n      - \"playlist.txt\"\n```\n\n## RTMP Streaming\nGroovebox can stream to any RTMP server, including YouTube and Twitch. To stream to an RTMP server, you will need the RTMP URL and Stream Key from your streaming platform.\n\n### RTMP Stream Server\nUse the high-performance built-in RTMP server to receive and redistribute streams to other clients. To start the RTMP server, run:\n\nCurrently there is no specific config for the Groovebox RTMP server, you can use `.` to skip cli validation and run the server directly:\n\n```\ngroovebox rtmp.server .\n```\n\nThe server will listen on rtmp://127.0.0.1:1935 by default.\n\n### RTMP Stream Client\nUse the `rtmp.stream` command to stream media to a RTMP server. The `groovebox.config.yaml` file should specify the RTMP server url and the playlists for video and audio:\n\n```yaml\n# stream media to an RTMP server\ntype: rtmp\nstream:\n  url: \"rtmp://127.0.0.1/live/livestream\"\n  video:\n    - \"./videoplaylist.txt\"\n  audio:\n    - \"./audioplaylist.txt\"\n```\n\n### Why use Groovebox instead of ffmpeg/OBS Studio for streaming to RTMP servers?\n- 👌 **Simplicity**: Groovebox provides a simple and intuitive interface for streaming pre-recorded media to RTMP servers, without the need to write complex ffmpeg command lines.\n- 🎧 **Playlist Management**: Groovebox has built-in support for managing playlists, allowing you to easily organize and shuffle your media files for streaming sessions.\n- 📁 **Zero-Copy Streaming**: Groovebox is designed to stream media directly from the source file to the network without fully loading it into memory, which makes it more efficient for streaming large media files without consuming excessive system resources.\n- 🕊 **Lightweight**: Groovebox is a lightweight application that is optimized for streaming, while ffmpeg is a powerful multimedia framework that can be used for a wide range of media processing tasks, which may be overkill for simple streaming use cases.\n- 💪 **No GPU required**: OBS Studio is a popular streaming software that provides advanced features for live streaming, but it requires GPU acceleration for video encoding and processing, which may not be available on all systems. Groovebox, on the other hand, does not require any GPU acceleration as it does not perform any video encoding or decoding itself.\n- 💫 **Ideal for VPS streaming**: Groovebox is designed to be fast and efficient, making it ideal for streaming sessions from a basic VPS (Virtual Private Server) without the need for a GPU, or too much CPU/RAM resources.\n\n\n### FAQs\nHere are some questions and answers about Groovebox, so you can better understand its capabilities and limitations:\n\n#### Can I use Groovebox for live streaming from a webcam or microphone?\nNo, Groovebox is designed for streaming pre-recorded media files from playlists. It does not capture live input from webcams or microphones. For live streaming from a webcam or microphone, you may want to use software like OBS Studio or Streamlabs.\n\n#### Can I use Groovebox for streaming video content?\nYes, Groovebox can be used for streaming video content to RTMP servers. However, it does not perform any video encoding or decoding itself, so you will need to ensure that your video files are in a format that is compatible with your streaming platform and that they are properly encoded for streaming. You can use the built-in CLI commands to convert media files to formats suitable for streaming using ffmpeg.\n\n#### Can I use Groovebox for streaming to platforms other than YouTube and Twitch?\nYes, Groovebox can stream to any RTMP server, including platforms other than YouTube and Twitch. You will need to obtain the RTMP URL and Stream Key from your streaming platform and configure Groovebox accordingly.\n\n\n#### Is Groovebox just a client for streaming to external RTMP servers, or does it also include a server implementation?\nGroovebox includes both a client for streaming to external RTMP servers and a built-in RTMP server implementation that can be used to receive and redistribute streams to other clients. You can use the built-in RTMP server to set up your own streaming server or to receive streams from other sources.\n\n#### Can I use Groovebox for streaming to Icecast-compatible servers?\nYes, Groovebox is designed to be compatible with Icecast2 servers, allowing you to stream audio content to Icecast-compatible servers. You can configure Groovebox to stream your media files to an Icecast-compatible server by providing the necessary server details in the configuration file.\n\n## Roadmap\nSource Client\n- [ ] Handle multiple playlists\n- [x] Zero-copy live streaming pre-recorded media to RTMP servers\n- [x] Support for streaming to Icecast-compatible servers\n- [x] Support for streaming to YouTube/Twitch RTMP servers\n- [x] Shuffle playlists\n- [ ] Improve the shuffle algorithm (ensure no repeats until all tracks played)\n- [ ] Add support for more audio formats\n- [ ] Add support for video streaming\n- [ ] Add web interface for monitoring and control\n- [ ] Support ads insertion\n- [ ] Live streaming from non non-seekable sources (e.g. stdin) via ffmpeg\n\nServer\n- [ ] Implement a Icecast-compatible based on Libevent\n- [ ] Middleware Authentication using JWT\n- [ ] Subscriber management\n- [ ] Rate Limiting and Anti-abuse\n- [ ] Analytics and Reporting Dashboard\n\n### ❤ Contributions \u0026 Support\n- 🐛 Found a bug? [Create a new Issue](https://github.com/openpeeps/groovebox/issues)\n- 👋 Wanna help? [Fork it!](https://github.com/openpeeps/groovebox/fork)\n- 😎 [Get €20 in cloud credits from Hetzner](https://hetzner.cloud/?ref=Hm0mYGM9NxZ4)\n\n### 🎩 License\nAGPLv3 license. [Made by Humans from OpenPeeps](https://github.com/openpeeps).\u003cbr\u003e\nCopyright OpenPeeps \u0026 Contributors \u0026mdash; All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenpeeps%2Fgroovebox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenpeeps%2Fgroovebox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenpeeps%2Fgroovebox/lists"}