Skip to content

Added Queue Artist Intent #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Rusketh merged 1 commit into from
Nov 27, 2025
Merged

Added Queue Artist Intent #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 24 additions & 114 deletions ReadMe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,41 @@



# Jelly Music




---



## What is Jelly Music?



Jelly Music is a **self-hosted Alexa Skill** designed for your Jellyfin server. It allows for you to stream and play music on your Alexa devices using voice commands like:



* "Alexa, ask Jelly Music to play album **Creeping Death** by Metallica."

* "Alexa, ask Jelly Music to shuffle songs by **Black Sabbath**."




---



## Features


* Per device music queues.

* Play music from your Jellyfin server.

* Support to search by, **Song Name**, **Album Name**, **Artist Name**, **Playlist** and **Genre***.




---



## Alpha Software Disclaimer



Please note that **Jelly Music** is a side project I'm developing in my spare time.



* There's **no guarantee** of ongoing maintenance or updates.

* Not all features will be thoroughly tested upon release, so exercise **caution when updating**.

* This software comes with **no guarantees of functionality**. I am not an experienced programmer; I'm simply an enthusiast with a hobby.



---



## Requirements



To run a Jelly Music instance, you will need:



* A basic understanding of setting up **Docker containers**.

* The ability to log into the **Alexa Developer Dashboard** (creating an account is straightforward).
Expand All @@ -83,16 +46,10 @@ To run a Jelly Music instance, you will need:

* **Recommendation:** Set up an **NGINX reverse proxy server** and **Dynamic DNS (DDNS)** to achieve the public accessibility and trusted certificates.



---



## Installation Instructions



1. Set up the Docker container using the latest [**Docker image**](https://ghcr.io/rusketh/jellymusic/jellymusic).

2. Ensure you **enable the necessary port** in your Docker configuration.
Expand All @@ -101,24 +58,14 @@ To run a Jelly Music instance, you will need:

4. Map or bind a **Data Directory** ``/data``



Here's an example of a `docker run` command:



``docker run -e JELLYFIN_HOST="https://jellyfin.example.com" -e JELLYFIN_KEY="replace_with_your_api_key" -e SKILL_NAME="jelly music" -e PORT="60648" -p 60648:60648 -v "data:/data" ghcr.io/rusketh/jellymusic/jellymusic:main``



### Enviroment Variables



The following environment variables are **required**:



* **`JELLYFIN_HOST`**: The public address of your Jellyfin server.

* **`JELLYFIN_KEY`**: The API key for your Jellyfin server.
Expand All @@ -127,36 +74,20 @@ The following environment variables are **required**:

* **`PORT`**: The Port your server will use (remember to enable this port on Docker).



**Note:** Your public address for the server needs to run on port `443`, and your reverse proxy should handle the redirect to the specified `PORT`.



### Data Directory



The **configuration file** for Jelly Music, as well as the **SQLite database** used to store the song queue for each connected device, are saved within the `/data` directory.



**Important Considerations:**



- This directory **must be mapped as a volume** in your Docker container to ensure data persistence. Without it, your configuration will be lost when the container stops or is removed.



---



## Alexa Skill Setup



1. Create an account on the **Alexa Developer Console** using your Amazon account: [https://developer.amazon.com](https://developer.amazon.com)

2. Create a **new skill** named `Jelly Music`.
Expand All @@ -167,16 +98,10 @@ The **configuration file** for Jelly Music, as well as the **SQLite database** u

5. For "Hosting Service," choose **"Provision your own"**.



**Note:** This container will **not** work with Alexa-Hosted skills.



Once your Alexa Skill is created, you need to configure it. This might seem daunting, but it's quite simple as most of the work has been done for you.



1. Navigate to **"Endpoint"** and select **"HTTPS"**. Set "Default Region" to the **public address of your Jelly Music server**.

2. Navigate to **"Interfaces"** and **enable "Audio Player"**. This is crucial for audio streaming, and the skill will not function without it.
Expand All @@ -187,21 +112,14 @@ Once your Alexa Skill is created, you need to configure it. This might seem daun

5. Navigate to **"Interaction Model"** and open the **"JSON Editor"**. Drag your saved JSON file into the editor (or copy and paste its contents).



That's it! Click **"Save"** at the top, then hit **"Build Skill"**. Hopefully, after a few minutes, it will build successfully, and you'll be ready to go and install the skill. Start the container and enjoy listening to your music!

**Note:** When upgrading to new versions **New Features** will require you to update your ``skill.json`` as described in steps 3 - 4.


### Enabling Your Skill in the Alexa App



Once your Docker container is running and your Alexa Skill is successfully built in the Alexa Developer Console, you need to enable it within your Alexa app on your mobile device.



1. Open the **Alexa app** on your smartphone or tablet.

2. Navigate to the **"More"** menu (usually represented by three lines or dots).
Expand All @@ -216,47 +134,39 @@ Once your Docker container is running and your Alexa Skill is successfully built

7. Tap the **"Enable"** or **"Enable to Use"** button.



Your Jelly Music skill should now be active and ready for use on your Alexa devices!



---



## Commands



You can use the following commands with Alexa:



"Alexa, ask Jelly Music to..."



* **Play/Shuffle/Queue** the album `{album name}` [by `{artist name}`]

* **Play/Shuffle/Queue** songs by `{artist name}`

* **Play/Shuffle/Queue** songs [by `{artist name}`]
* **Play/Queue** `{song name}` [by `{artist name}`]

* **Play/Queue/Shuffle** playlist `{playlist name}`

* **Play/Queue/Shuffle** `{genre}` music

* Clear the queue

* **Play/Queue/Shuffle** `{genre}` music
* **Clear the queue**
As well as using simple commands like stop, play, pause, resume and next.

---


### Intents

Here is a list of all the current none standard intents used, the example commands and what they do.
| Intent | Command | Description |
|--|--|--|
| PlaySongIntent | Play song {song} by {artist} | Plays {song} ``(clears queue)``. |
| PlayAlbumIntent | Play the album {album} by {artist} | Plays {album} ``(clears queue)``. |
| PlayArtistIntent | Play songs by {artist} | Plays songs by {artist} ``(clears queue)``. |
| PlayPlaylistIntent | Play playlist {playlist} | Plays songs from {playlist} ``(clears queue)``. |
| PlayGenreIntent | Play {genre} music | Plays music of {genre} ``(clears queue)``. |
| ShuffleAlbumIntent | Shuffle the album {album} by {artist} | Plays & shuffles {album}``(clears queue)``. |
| ShuffleArtistIntent | Shuffle songs by {artist} | Plays & shuffles songs by {artist} ``(clears queue)``.
| ShufflePlaylistIntent | Shuffle playlist {playlist} | Plays & shuffles songs from {playlist} ``(clears queue)``. |
| ShuffleGenreIntent | Shuffle {genre} music | Plays & shuffles music of {genre} ``(clears queue)``. |
| QueueSongIntent | Add {song} to the queue | Adds {song} to queue |
| QueueAlbumIntent | Add the album {album} by {artist} to the queue | Adds {album} to the queue. |
| QueueArtistIntent | Add songs by {artistname} to the queue | Adds songs by {artistname} to the queue. |
| QueuePlaylistIntent | Add playlist {playlist} to the queue | Adds songs from {playlist} to the queue. |
| QueueGenreIntent | Queue {genre} music | Adds {genre} music to the queue. |
---

## Help Developing



As mentioned, this is a work in progress, and I'm not the most skilled programmer. I would be very grateful to anyone who contributes a **Pull Request (PR)** to this project. All I ask is that you try to adhere to my coding style and **test your work** before committing.
2 changes: 1 addition & 1 deletion src/playlist/devices.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ const onPlaybackFailed = function(handlerInput)

const playlist = getPlayList(deviceID);

const directive = playlist.getPlayDirective(handlerInput);
var directive = playlist.getPlayDirective(handlerInput);

console.debug("Playback failed!");

Expand Down
26 changes: 25 additions & 1 deletion src/skill/skill.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"interactionModel": {
"languageModel": {
"invocationName": "media server",
"invocationName": "jelly music",
"intents": [
{
"name": "AMAZON.CancelIntent",
Expand Down Expand Up @@ -248,6 +248,30 @@
"shuffle {genre} music",
"shuffle genre {genre}"
]
},
{
"name": "WhatThisIntent",
"slots": [],
"samples": [
"what is playing",
"what is this",
"what is the name of this song",
"What is this song"
]
},
{
"name": "QueueArtistIntent",
"slots": [
{
"name": "artistname",
"type": "AMAZON.Musician"
}
],
"samples": [
"add songs by {artistname} to the queue",
"queue artist {artistname}",
"queue songs by {artistname}"
]
}
],
"types": []
Expand Down