Tidal Helper

A tool to help manage Tidal music playlists and songs.

Note: This project is currently in early development.

Tech Stack

• Backend: Python 3.14, FastAPI, SQLModel, Alembic
• Frontend: TypeScript, Vue.js 3, Pinia, Tailwind CSS
• Database: SQLite
• Infrastructure: Docker, Docker Compose

Getting Started

Prerequisites

• Docker and Docker Compose installed on your machine.

Installation & Running

1. Clone the repository:

   git clone <repository-url>
   cd tidal-helper

2. Environment Setup: Create a .env file from the example template:

   cp .env.example .env

3. Start the Application: Run the following command to build and start the services:

   docker-compose up --build

4. Access the Application:

   • Frontend: http://localhost:22002
   • Backend API Docs: http://localhost:22001/docs

Development

Backend (Local)

cd backend
poetry install
poetry run uvicorn app.main:app --reload

Frontend (Local)

cd frontend
npm install
npm run dev

Database Management

Database Migrations with Alembic

The project uses Alembic for database schema migrations.

Initialize Alembic (First Time Only)

If the alembic directory doesn't exist, initialize it:

cd backend
poetry run alembic init alembic

Create a New Migration

After modifying your SQLModel models, generate a new migration:

cd backend
poetry run alembic revision --autogenerate -m "Description of changes"

This will create a new migration file in backend/alembic/versions/.

Apply Migrations

To apply all pending migrations to the database:

cd backend
poetry run alembic upgrade head

Rollback Migrations

To rollback the last migration:

cd backend
poetry run alembic downgrade -1

To rollback to a specific revision:

cd backend
poetry run alembic downgrade <revision_id>

Check Current Migration Status

To see the current migration version:

cd backend
poetry run alembic current

To see migration history:

cd backend
poetry run alembic history

Initialize Database (Alternative Method)

For quick database initialization without migrations, you can use the init_db.py script:

cd backend
poetry run python init_db.py

Note: This creates all tables based on your SQLModel definitions but doesn't track migration history. For production use, prefer Alembic migrations.

Music Backup

This project utilizes tiddl for music downloads and backups.

Note: A local version of tiddl is currently included in this repository to incorporate specific fixes that are pending approval in the upstream repository. Once these changes are merged, this local dependency will be removed in favor of the official library.