jellyfin-alexa-skill 0.3.1

Selfhosted Alexa media player skill for Jellyfin

Jellyfin Alexa Skill

Selfhosted Alexa media player skill for Jellyfin

---

---

Note: This project is still in a very early alpha phase, this means not all features are fully functional yet and features or usage can change significantly between releases. Moreover, new releases can result in data loss of the skill database.

Table of Contents

1. About
2. Features
3. Installation
4. Supported languages
5. Skill speech examples
6. Project plan
7. FAQ
8. Development
9. Third party notices
10. License

About

This is a self-hosting Alexa skill to play media from your Jellyfin server. Besides simple playback, other additional functions like playback of playlists or managing favorites are included. The skill and the Jellyfin player can be used behind a NAT or firewall without port opening/forwarding. Since the skill and also the Jellyfin server must be reachable from the outside, in this case the two services are exposed with a tunnel.

Features

• playback control:
  • play a specific media
  • play media from an artist
  • pause/resume/stop/cancel a playback
  • play previous/next song in queue
  • repeat a single media
  • repeat all media in queue
  • shuffle mode
  • play internet radio streams
  • navigate through top search results
• playlist:
  • play a specific playlist
• favorite:
  • play favorite media
  • mark current media as favorite
  • remove current media from favorites
• metadata:
  • show the metadata of the media (title and artist)
  • show cover art of the media
• other:
  • multi-language support (see Supported languages)
  • multi-user support (any user on the Jellyfin server can use the skill)

If you have a feature idea, use this issue template to suggest your idea for implementation.

Installation

Before you begin, make sure you meet the following requirements:

• up-to-date Jellyfin Server with public or local access
• free Amazon developer account
• python 3.6+ or docker + docker-compose installed
• optional:
  • free ngrok account if you're running a local access server

The initial setup requires several steps:

1. create a Alexa skill:
   1. go to the Amazon Developer Console webpage for Alexa and create a new skill
   2. now fill out the skill setup settings:
      1. the skill name can be custom, there are no requirements
      2. choose one of the supported languages of this skill for the Primary locale
      3. choose Custom for the model type
      4. choose Provision your own for the skill's backend resources
      5. on the next page choose Start from Scratch
2. generate SMAPI tokens:
   1. create a new security profile for the SMAPI access described here to get a CLIENT-ID and CLIENT-SECRET
   2. install npm if you have not already installed it and install the ask-cli package: npm install ask-cli -g
   3. now setup the ask cli: ask configure
   4. use the client id and client secret from step i. to generate the refresh token: ask util generate-lwa-tokens --client-id <CLIENT-ID> --client-confirmation <CLIENT-SECRET>

Note: The Skill id is needed for the interaction with the Alexa Skill. The SMAPI access is needed for the automatic setup of the skill.

Use this config file and adjust the values which are commented as required in the config file. Save the file in a safe place, because the file contains sensitive credentials. Also remember the save path, because the config file will be used again later.

Now you are ready to perform the actual installation and startup, you have two options to use the project:

1. use docker:
   • you can build the image locally or use the prebuild images on Github container registry
     • if you want to build the Docker image locally, use this commands (this clones the last release, you can also adjust the version to use older releases):

       git clone -b 0.3.1 https://github.com/infinityofspace/jellyfin_alexa_skill
       cd jellyfin_alexa_skill
       docker build -t jellyfin_alexa_skill:latest .
       

   • start the skill:

     docker run \
     -v /path/to/the/skill.conf:/var/lib/jellyfin_alexa_skill/config/skill.conf \
     -v /path/to/persistence/skill/data:/var/lib/jellyfin_alexa_skill/data \
     ghcr.io/infinityofspace/jellyfin_alexa_skill:latest
     

OR

2. with pip:
   • install:
     • from pypi:pip3 install jellyfin_alexa_skill
     • you can also install from source:

       git clone -b 0.3.1 https://github.com/infinityofspace/jellyfin_alexa_skill
       cd jellyfin_alexa_skill
       python3 setup.py install
       

   • start the skill: jellyfin_alexa_skill --config /path/to/skill.conf --data /path/to/skill/data/

Note: The default path for the skill.conf file is /home/user/.jellyfin_alexa_skill/config/skill.conf and for the skill data path it is /home/user/.jellyfin_alexa_skill/data. You can adjust the paths with the config and data or as environment variables JELLYFIN_ALEXA_SKILL_CONFIG and JELLYFIN_ALEXA_SKILL_DATA. Make sure the skill.conf is writeable.

Now activate the skill in your Alexa app and link your Jellyfin account. Now you can use the skill with your Alexa enabled devices.

Supported languages

The skill has support for the following languages:

• English
• German

Skill speech examples

The wiki contains examples how to interact with the skill.

Project plan

Take a look at the project plan to see what features and bug fixes are planned and in progress.

FAQ

You can find the FAQ here.

Development

You can find more guidelines for the development here.

Third party notices

Module	License	Project
flask-ask-sdk	License	Project
pyngrok	License	Project
ask-smapi-sdk	License	Project
ask-smapi-model	License	Project
rapidfuzz	License	Project
peewee	License	Project
gunicorn	License	Project
Babel	License	Project
Flask-WTF	License	Project
requests	License	Project

Furthermore, this readme file contains embeddings of Shields.io.

License

GPL-3.0