# Jelly Music App (JMA)

A modern, elegant music player for your personal Jellyfin library. Designed for seamless playback, beautiful UI, and easy self-hosting—whether for yourself, family, or friends.

---

## Project Overview
- **What is it?**
  - A web and PWA app for browsing, searching, and playing music from your Jellyfin server.
  - Built with React (frontend) and Python Flask (backend), deployable via Docker or manually.
- **Who is it for?**
  - Anyone who wants a beautiful, cross-device music player for their own or shared Jellyfin library.
- **How does it work?**
  - Connects to your Jellyfin server (and optionally Spotify for discovery/downloads).
  - Supports multiple users/servers with isolated libraries and playlists.

---

## Quick Start (Production)

### 1. **Docker (Recommended)**
```bash
# Clone the repo
cd /your/app/path
# Copy example env and edit as needed
cp setup/.env.example .env
# Edit .env with your Jellyfin/Spotify info
nano .env
# Build and start
sudo docker-compose up -d
```
- App will be at `http://localhost:5143` (or your chosen port)

### 2. **Manual (Dev/Advanced)**
```bash
yarn install
pip install -r server/requirements.txt
yarn build
python server/app.py
```

---

## Deploying for a New User/Server

1. **Copy only the essentials:** `src/`, `server/`, `public/`, `.env`, `docker-compose.yml`, `Dockerfile`, `Dockerfile.ui`, `package.json`
2. **Go to `setup/` and run the setup script:**
   ```bash
   bash setup/new_server_setup.sh
   ```
   - This will prompt for all required info (keys, URLs, output paths) and generate a ready-to-use `.env` and compose file.
3. **Start the app:**
   ```bash
   sudo docker-compose -f setup/docker-compose.YOURNAME.yml up -d
   ```
4. **Access at:** `http://your-server-ip:YOUR_FRONTEND_PORT`

---

## What to Customize for Each Server/User
- **Spotify Keys:** For most personal/family use, you can share your key. For heavy/public use, each user/server should register their own at [Spotify Developer Dashboard](https://developer.spotify.com/dashboard).
- **Jellyfin URL/API Key:** Each user/server must set their own Jellyfin URL and API key.
- **Output Directories:** Set unique paths for music and playlists per user/server to avoid conflicts.
- **Port Numbers:** Change in compose file if running multiple instances.

---

## Setup Script for New Users/Servers
- Run `bash setup/new_server_setup.sh`
- Script will prompt for:
  - Spotify client ID/secret
  - Jellyfin URL/API key
  - Output directory paths
  - Playlist name
  - Port numbers
- It will generate a `.env` and a compose file for you in `setup/`.

---

## Where to Find More Info
- **Detailed guides and config explanations:** See `docs/`
- **Per-user configs and setup script:** See `setup/`
- **Feature list, screenshots, and advanced usage:** See below

---

## Features

(Elegant & Simple Design...)

<!-- Keep your existing feature list and screenshots below this line -->


-   **Elegant & Simple Design:** A clean, clutter-free interface that makes music playback effortless and enjoyable. Built with modern tools like React for a snappy, reliable experience.
-   **Device Friendly:** Enjoy a smooth, app-like experience on mobile and desktop alike, installable as a PWA for instant access.
-   **Seamless Library Access:** Connect to your Jellyfin server to explore your personal music collection with ease.
-   **Discover Your Favorites:**
    -   **Home:** Jump back in with recently played tracks, your most-played favorites, and newly added media.
    -   **Artists:** Browse top tracks, albums, and collaborations for any artist in your library.
    -   **Playlists:** View playlists with a clear, numbered tracklist for quick navigation.
    -   **Quick Search:** Find tracks, artists, albums, playlists, or genres effortlessly with a sidenav search or dedicated results page.
    -   **Instant Mix:** Enjoy curated playlists directly from your music library on a standalone page.
-   **Queue:** Effortlessly manage and reorder tracks with the enhanced and improved Queue functionality.
-   **Crossfade:** Smoothly transition between tracks for a seamless and immersive listening experience.
-   **Synchronized Lyrics:** Enjoy your favorite songs in a new way with a spectacular UI showing perfectly timed lyrics that appear line-by-line as you listen.
-   **Smart Fetching:** Caches your music efficiently for instant, smooth playback.
-   **Offline Sync:** Download individual songs, full albums, playlists, or artists for offline playback.
    -   **Auto-Sync:** Automatically downloads newly added tracks to any previously saved playlist, album, or artist.
    -   **Persistent Queue:** Downloads are managed with a local queue that resumes seamlessly across sessions.
    -   **Transcoded or Direct Streams:** Supports both original quality and transcoded downloads based on your selected bitrate.
-   **Docker Support:** Pull and deploy the app using a pre-built Docker image with a pre-configured Jellyfin server URL for seamless self-hosting.

### Installation

Jelly Music App can be installed as a dedicated desktop app, available on our [GitHub release page](https://github.com/Stannnnn/jelly-app/releases). You can also get the latest production build from there and deploy it on your web server by placing the archived folder's contents in a web-accessible directory.
<br/>
It's also available as a **docker image** for easy deployment, see docker details below.
<br/>
<br/>

[Yarn](https://classic.yarnpkg.com/lang/en/docs/install) (`npm i -g yarn`) is required if you wish to build the project or run the development server yourself.

#### Build from Source

1. Clone the repository:
    ```bash
    git clone https://github.com/Stannnnn/jelly-app.git
    ```
2. Install dependencies:
    ```bash
    yarn
    ```
3. Build the production files:
    ```bash
    yarn build
    ```
4. Deploy the contents of the `dist` folder to a web-accessible directory.

Alternatively, you can run the development server directly: `yarn dev` or `yarn dev:nocache`

If you wish to use a base path for the application other than root (`/`), you must build it manually while setting `URL_BASE_PATH` to your preferred base path.

Leave the configuration as the default, or change [`config.json`](public/config.json) as needed. Configurations are explained on the [App Configuration Section](#app-configuration).
The `config.json` file can be changed directly in the built application afterwards. There is no need to rebuild if only changing a configuration variable.

### Docker

You can easily host Jelly Music App using Docker with the prebuilt image from ghcr.io:

#### Pull the docker image

```bash
docker pull ghcr.io/stannnnn/jelly-music-app:latest
```

#### Run the docker image

```bash
docker run --rm -p 80:80 ghcr.io/stannnnn/jelly-music-app:latest
```

Docker image can also be run in the background by adding the -d flag `docker run -d ...`

#### Run the docker image with configuration variables

```bash
docker run --rm \
    -e DEFAULT_JELLYFIN_URL=https://demo.jellyfin.org/stable \
    -e LOCK_JELLYFIN_URL=false \
    -p 80:80 ghcr.io/stannnnn/jelly-music-app:latest
```

<br/>

The following are the available tags for docker:

| Tag    | Description                |
| ------ | -------------------------- |
| latest | Tracks most recent release |
| main   | Tracks the main branch     |
| vX.X.X | Version specific tags      |

E.g: `ghcr.io/stannnnn/jelly-music-app:latest`

#### Docker Container Build

You can also build Jelly Music App using Docker.

1.  Build the Docker image:

    ```bash
    docker build . --tag jelly-music-app
    ```

2.  Run the Docker container:

    ```bash
    docker run --rm -p 80:80 jelly-music-app:latest
    ```

    You can also provide configuration using environment variables.

    ```bash
    docker run --rm \
        -e DEFAULT_JELLYFIN_URL=https://demo.jellyfin.org/stable \
        -e LOCK_JELLYFIN_URL=false \
        -p 80:80 jelly-music-app:latest
    ```

### App Configuration

App configuration can be modified by editing the `config.json` file during the build process or in the release files. When using Docker, configurations can be provided as environment variables. The available configuration options are as follows:

-   `DEFAULT_JELLYFIN_URL`: Sets the default Jellyfin server URL loaded on first app access if no URL is stored in Local Storage.
-   `LOCK_JELLYFIN_URL`: If set to `true`, removes the URL input field and enforces the default URL (`DEFAULT_JELLYFIN_URL`) for all connections, ideal for self-hosted instances tied to a single server.

### Contributing

We're open to pull requests, please merge them to the `develop` branch. If you have any suggestions or improvements, feel free to open an issue or submit a pull request. Your contributions are welcome and appreciated!
=======
# Music App for Jellyfin



## Getting started

To make it easy for you to get started with GitLab, here's a list of recommended next steps.

Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!

## Add your files

- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
- [ ] [Add files using the command line](https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository) or push an existing Git repository with the following command:

```
cd existing_repo
git remote add origin https://gitlab.com/JEEZYSAM/music-app-for-jellyfin.git
git branch -M main
git push -uf origin main
```

## Integrate with your tools

- [ ] [Set up project integrations](https://gitlab.com/JEEZYSAM/music-app-for-jellyfin/-/settings/integrations)

## Collaborate with your team

- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
- [ ] [Set auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)

## Test and Deploy

Use the built-in continuous integration in GitLab.

- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/)
- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)

***

# Editing this README

When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.

## Suggestions for a good README

Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.

## Name
Choose a self-explaining name for your project.

## Description
Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.

## Badges
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.

## Visuals
Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.

## Installation
Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.

## Usage
Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.

## Support
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.

## Roadmap
If you have ideas for releases in the future, it is a good idea to list them in the README.

## Contributing
State if you are open to contributions and what your requirements are for accepting them.

For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.

You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.

## Authors and acknowledgment
Show your appreciation to those who have contributed to the project.

## License
For open source projects, say how it is licensed.

## Project status
If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
>>>>>>> 008b18956e77ad7d74b2800d5a98bcab12111fe1