Getting Started¶

Prerequisites¶

Installation¶

Clone the repository and install dependencies:

git clone https://github.com/fstermann/starlib.git
cd starlib

Backend¶

uv sync

Frontend¶

cd frontend
npm install

Configuration¶

Create a .env file in the project root with your SoundCloud credentials:

CLIENT_ID=your_client_id_here
CLIENT_SECRET=your_client_secret_here
USER_ID=your_soundcloud_user_id

How to get credentials:

1. Register your app at the SoundCloud Developer Portal
2. Copy CLIENT_ID and CLIENT_SECRET from your app settings
3. Add them to the .env file

Running the application¶

Start both services:

# Terminal 1 – Backend
uv run python -m backend.main

# Terminal 2 – Frontend
cd frontend && npm run dev

The backend API is available at http://localhost:8000 and the frontend at http://localhost:3000.

API documentation¶

Once the backend is running, interactive API docs are available at:

• Swagger UI: localhost:8000/docs
• ReDoc: localhost:8000/redoc

CLI¶

Starlib ships a starlib command for common dev tasks.

Installation¶

Install it once as a global uv tool so it's available in every shell:

uv tool install --editable .
uv tool update-shell   # adds ~/.local/bin to PATH (restart shell after)

After restarting your shell, starlib is available globally.

Commands¶

starlib screenshot¶

Fetches fresh track metadata from the iTunes Search API, then runs the Playwright screenshot suite (screenshots.spec.ts) and writes PNGs to docs/assets/images/screenshots/. The track cache is stored in .cache/screenshot-tracks.json.

starlib screenshot

Make sure the frontend dev server is running (cd frontend && npm run dev) before capturing screenshots, or let Playwright start it automatically via reuseExistingServer.

Running tests¶

uv run python -m pytest tests/ -v