{"id":14983167,"url":"https://github.com/museofficial/muse","last_synced_at":"2026-04-26T09:04:43.176Z","repository":{"id":37021611,"uuid":"245718600","full_name":"museofficial/muse","owner":"museofficial","description":"🎧 a self-hosted midwestern Discord music bot that doesn't suck","archived":false,"fork":false,"pushed_at":"2025-04-11T10:37:13.000Z","size":3278,"stargazers_count":1045,"open_issues_count":111,"forks_count":280,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-12T01:51:44.519Z","etag":null,"topics":["discord","discord-js","music","spotify","youtube"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/museofficial.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["codetheweb"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-03-07T23:04:00.000Z","updated_at":"2025-04-11T22:05:42.000Z","dependencies_parsed_at":"2023-02-10T14:15:47.048Z","dependency_job_id":"0c327119-84cd-47ed-87d4-7d9b2832eaf6","html_url":"https://github.com/museofficial/muse","commit_stats":{"total_commits":653,"total_committers":42,"mean_commits":"15.547619047619047","dds":0.6171516079632465,"last_synced_commit":"534d8fafaa7f09f7ba940d044b08e6c48f800c7a"},"previous_names":["museofficial/muse"],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/museofficial%2Fmuse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/museofficial%2Fmuse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/museofficial%2Fmuse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/museofficial%2Fmuse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/museofficial","download_url":"https://codeload.github.com/museofficial/muse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248505873,"owners_count":21115354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["discord","discord-js","music","spotify","youtube"],"created_at":"2024-09-24T14:06:50.216Z","updated_at":"2026-04-26T09:04:43.170Z","avatar_url":"https://github.com/museofficial.png","language":"TypeScript","funding_links":["https://github.com/sponsors/codetheweb"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"250\" height=\"250\" src=\"https://raw.githubusercontent.com/museofficial/muse/master/.github/logo.png\"\u003e\n\u003c/p\u003e\n\n\u003e [!WARNING]\n\u003e I ([@codetheweb](https://github.com/codetheweb)) am no longer the primary maintainer of Muse. **If you use the Docker image, update your image source to `ghcr.io/museofficial/muse`.** We are currently publishing new releases to both `ghcr.io/museofficial/muse` and `codetheweb/muse`, but this may change in the future.\n\u003e Thank you to all the people who stepped up to help maintain Muse!\n\n------\n\nMuse is a **highly-opinionated midwestern self-hosted** Discord music bot **that doesn't suck**. It's made for small to medium-sized Discord servers/guilds (think about a group the size of you, your friends, and your friend's friends).\n\n![Hero graphic](.github/hero.png)\n\n## Features\n\n- 🎥 Livestreams\n- ⏩ Seeking within a song/video\n- 💾 Local caching for better performance\n- 📋 No vote-to-skip - this is anarchy, not a democracy\n- ↔️ Autoconverts playlists / artists / albums / songs from Spotify\n- ↗️ Users can add custom shortcuts (aliases)\n- 1️⃣ Muse instance supports multiple guilds\n- 🔊 Normalizes volume across tracks\n- ✍️ Written in TypeScript, easily extendable\n- ❤️ Loyal Packers fan\n\n## Running\n\nMuse is written in TypeScript. You can either run Muse with Docker (recommended) or directly with Node.js. Both methods require API keys passed in as environment variables:\n\n- `DISCORD_TOKEN` can be acquired [here](https://discordapp.com/developers/applications) by creating a 'New Application', then going to 'Bot'.\n- `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` can be acquired [here](https://developer.spotify.com/dashboard/applications) with 'Create a Client ID' (Optional).\n- `YOUTUBE_API_KEY` can be acquired by [creating a new project](https://console.developers.google.com) in Google's Developer Console, enabling the YouTube API, and creating an API key under credentials.\n\nMuse will log a URL when run. Open this URL in a browser to invite Muse to your server. Muse will DM the server owner after it's added with setup instructions.\n\nA 64-bit OS is required to run Muse.\n\n### Versioning\n\nThe `master` branch acts as the developing / bleeding edge branch and is not guaranteed to be stable.\n\nWhen running a production instance, I recommend that you use the [latest release](https://github.com/museofficial/muse/releases/).\n\n\n### 🐳 Docker\n\nThere are a variety of image tags available:\n- `:2`: versions \u003e= 2.0.0\n- `:2.1`: versions \u003e= 2.1.0 and \u003c 2.2.0\n- `:2.1.1`: an exact version specifier\n- `:latest`: whatever the latest version is\n- `:yt-dlp-latest`: the latest release rebuilt with the newest available `yt-dlp`\n\n(Replace empty config strings with correct values.)\n\n```bash\ndocker run -it -v \"$(pwd)/data\":/data -e DISCORD_TOKEN='' -e SPOTIFY_CLIENT_ID='' -e SPOTIFY_CLIENT_SECRET='' -e YOUTUBE_API_KEY='' ghcr.io/museofficial/muse:latest\n```\n\nThis starts Muse and creates a data directory in your current directory.\n\nYou can also store your tokens in an environment file and make it available to your container. By default, the container will look for a `/config` environment file. You can customize this path with the `ENV_FILE` environment variable to use with, for example, [docker secrets](https://docs.docker.com/engine/swarm/secrets/). \n\n**Docker Compose**:\n\n```yaml\nservices:\n  muse:\n    image: ghcr.io/museofficial/muse:latest\n    restart: always\n    volumes:\n      - ./muse:/data\n    environment:\n      - DISCORD_TOKEN=\n      - YOUTUBE_API_KEY=\n      - SPOTIFY_CLIENT_ID=\n      - SPOTIFY_CLIENT_SECRET=\n```\n\nIf you keep the same `DISCORD_TOKEN`, reuse the same `/data` volume, and point your Compose service at a newer image tag, Muse will come back up with the same bot identity and persisted database/cache.\n\n### Node.js\n\n**Prerequisites**:\n* Node.js (18.17.0 or latest 18.xx.xx is required and latest 18.x.x LTS is recommended) (Version 18 due to opus dependency)\n* ffmpeg (4.1 or later)\n* `yt-dlp` on your `PATH` (or set `YT_DLP_PATH` to its full path)\n\n1. `git clone https://github.com/museofficial/muse.git \u0026\u0026 cd muse`\n2. Copy `.env.example` to `.env` and populate with values\n3. I recommend checking out a tagged release with `git checkout v[latest release]`\n4. `yarn install` (or `npm i`)\n5. `yarn start` (or `npm run start`)\n\n**Note**: if you're on Windows, you may need to manually set the ffmpeg path. See [#345](https://github.com/museofficial/muse/issues/345) for details.\n\n## ⚙️ Additional configuration (advanced)\n\n### Cache\n\nBy default, Muse limits the total cache size to around 2 GB. If you want to change this, set the environment variable `CACHE_LIMIT`. For example, `CACHE_LIMIT=512MB` or `CACHE_LIMIT=10GB`.\n\n### yt-dlp\n\nMuse now uses `yt-dlp` to resolve playable YouTube media URLs. In Docker, the image already includes it. For direct Node.js installs, either put `yt-dlp` on your `PATH` or set `YT_DLP_PATH` in your environment file.\n\nMuse logs `YT_DLP_VERSION` on startup. Set `YT_DLP_AUTO_UPDATE=true` to make Muse try to update the configured `yt-dlp` installation before connecting to Discord. This works best with the Docker image's bundled virtualenv, or when `YT_DLP_PATH` points at a virtualenv or standalone `yt-dlp` executable that Muse can update.\n\nThe `ghcr.io/museofficial/muse:yt-dlp-latest` image is rebuilt on a schedule from the latest Muse release with the newest `yt-dlp` published to PyPI. Versioned refresh tags are also published as `:\u003cmuse-version\u003e-yt-dlp-\u003cyt-dlp-version\u003e`.\n\n### SponsorBlock\n\nMuse can skip non-music segments at the beginning or end of a Youtube music video (Using [SponsorBlock](https://sponsor.ajay.app/)). It is disabled by default. If you want to enable it, set the environment variable `ENABLE_SPONSORBLOCK=true` or uncomment it in your .env.\nBeing a community project, the server may be down or overloaded. When it happen, Muse will skip requests to SponsorBlock for a few minutes. You can change the skip duration by setting the value of `SPONSORBLOCK_TIMEOUT`.\n\n### Custom Bot Status\n\nIn the default state, Muse has the status \"Online\" and the text \"Listening to Music\". You can change the status through environment variables:\n\n- `BOT_STATUS`:\n  - `online` (Online)\n  - `idle` (Away)\n  - `dnd` (Do not Disturb)\n\n- `BOT_ACTIVITY_TYPE`:\n  - `PLAYING` (Playing XYZ)\n  - `LISTENING` (Listening to XYZ)\n  - `WATCHING` (Watching XYZ)\n  - `STREAMING` (Streaming XYZ)\n\n- `BOT_ACTIVITY`: the text that follows the activity type\n\n- `BOT_ACTIVITY_URL` If you use `STREAMING` you MUST set this variable, otherwise it will not work! Here you write a regular YouTube or Twitch Stream URL.\n\n#### Examples\n\n**Muse is watching a movie and is DND**:\n- `BOT_STATUS=dnd`\n- `BOT_ACTIVITY_TYPE=WATCHING`\n- `BOT_ACTIVITY=a movie`\n\n**Muse is streaming Monstercat**:\n- `BOT_STATUS=online`\n- `BOT_ACTIVITY_TYPE=STREAMING`\n- `BOT_ACTIVITY_URL=https://www.twitch.tv/monstercat`\n- `BOT_ACTIVITY=Monstercat`\n\n### Bot-wide commands\n\nIf you have Muse running in a lot of guilds (10+) you may want to switch to registering commands bot-wide rather than for each guild. (The downside to this is that command updates can take up to an hour to propagate.) To do this, set the environment variable `REGISTER_COMMANDS_ON_BOT` to `true`.\n\n### Automatically turn down volume when people speak\n\nYou can configure the bot to automatically turn down the volume when people are speaking in the channel using the following commands:\n\n- `/config set-reduce-vol-when-voice true` - Enable automatic volume reduction\n- `/config set-reduce-vol-when-voice false` - Disable automatic volume reduction\n- `/config set-reduce-vol-when-voice-target \u003cvolume\u003e` - Set the target volume percentage when people speak (0-100, default is 70)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuseofficial%2Fmuse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuseofficial%2Fmuse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuseofficial%2Fmuse/lists"}