CoolFace
Apppublic

Dell06/movie-songs-demo

sourceHugging Faceupdated 5mo agoView on Hugging Face
0likes
App README

Hybrid Cross-Modal Recommender Prototype

A runnable prototype that bridges movie swipe preferences into music recommendations.

Recommendation formula

R(u,s) = alpha * Sim(E_lyrics, E_movie) + beta * Sim(M_audio, M_movieMood)

  • —E_lyrics: candidate song lyric embedding.
  • —E_movie: centroid of embeddings from movies the user liked.
  • —M_audio: candidate song audio vector (valence, energy, acousticness, instrumentalness, tempo).
  • —M_movieMood: averaged mood vector from liked movies.

Repo layout

  • —src/hybrid_recommender.py: profile + ranking math.
  • —src/service.py: application service layer.
  • —src/app.py: FastAPI API.
  • —src/embedding_provider.py: pluggable embedding providers (local, openai).
  • —src/ingest.py: raw text -> embedding helper for ingestion pipelines.
  • —src/cli.py: local CLI for quick scoring.
  • —db/schema.sql: PostgreSQL + pgvector schema.
  • —data/movies.json: sample movie catalog.
  • —data/songs.json: sample song catalog.
  • —tests/: unit tests.

Quick start

1) Install dependencies

bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2) Run CLI prototype

bash
python3 src/cli.py --likes "Interstellar,Blade Runner 2049" --top-k 5

3) Run API

bash
uvicorn src.app:app --reload --host 0.0.0.0 --port 8000

API routes:

  • —GET / landing page
  • —GET /profile profile setup
  • —GET /movie movie-to-song recommender
  • —GET /aux Aux Battle
  • —GET /charts top-50 song page
  • —GET /health
  • —GET /movies
  • —POST /recommend

Example request:

bash
curl -X POST http://localhost:8000/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "likes": ["Interstellar", "Blade Runner 2049"],
    "top_k": 5,
    "alpha": 0.65,
    "beta": 0.35
  }'

Embedding providers

Use .env.example as a template.

  • —Local development:
  • —EMBEDDING_PROVIDER=local
  • —Real provider:
  • —EMBEDDING_PROVIDER=openai
  • —OPENAI_API_KEY=...
  • —OPENAI_EMBEDDING_MODEL=text-embedding-3-small

src/ingest.py uses the configured provider for movie plot and lyric text embedding.

Genius API setup

Genius is used here for song search/metadata, not an official Billboard chart feed. The app exposes /charts and /charts/top50; if GENIUS_ACCESS_TOKEN is present, it queries Genius search across genre/chart-style terms. If the token is missing, it falls back to local sample songs.

  1. 1.Go to https://genius.com/api-clients.
  2. 2.Create an API client.
  3. 3.Copy the client access token.
  4. 4.Add it to your environment:
bash
export GENIUS_ACCESS_TOKEN="your_token_here"
uvicorn src.app:app --reload --host 0.0.0.0 --port 8000

For Hugging Face Spaces, add GENIUS_ACCESS_TOKEN as a Space secret.

Dataset conversion

The repo includes a converter for your zipped datasets:

bash
python3 scripts/convert_datasets.py --limit 500

It reads:

  • —/Users/abdel/Downloads/data.csv.zip
  • —/Users/abdel/Downloads/Movie_combined.csv.zip

It writes:

  • —data/real_songs_sample.json
  • —data/real_movies_sample.json

Social features

Aux Battle lives at /aux. It lets two users create profiles, choose playlist names, pick songs within a genre, run a familiarity battle, and save unfamiliar songs into a shareable playlist link.

Song appearance scoring is available at POST /songs/appearance-score. The current formula is intentionally simple:

score = aux_battle_appearances + playlist_appearances + streams_since_joining

Database schema (pgvector)

Apply db/schema.sql to create:

  • —movies with plot_embedding vector(1536)
  • —songs with lyric_embedding vector(1536)
  • —movie_swipes for Tinder-style likes/dislikes
  • —user_profiles for cached hybrid centroids and weights

Tests

bash
python3 -m unittest discover -s tests

Public demo deploy (Render)

  1. 1.Go to Render, click New + -> Blueprint.
  2. 2.Connect your GitHub repo asricka/Movie_songs.
  3. 3.Render will detect render.yaml and create the web service.
  4. 4.Click Apply and wait for deploy to finish.
  5. 5.Open your live URL:
  6. 6.https://<your-render-service>.onrender.com/health
  7. 7.https://<your-render-service>.onrender.com/docs

Manual Render (without Blueprint)

  1. 1.New Web Service from your GitHub repo.
  2. 2.Runtime: Python.
  3. 3.Build Command: pip install -r requirements.txt
  4. 4.Start Command: uvicorn src.app:app --host 0.0.0.0 --port $PORT
  5. 5.Add env vars:
  6. 6.EMBEDDING_PROVIDER=local
  7. 7.MOVIES_PATH=data/movies.json
  8. 8.SONGS_PATH=data/songs.json

Alternative host (Railway/Heroku-style)

This repo includes a Procfile:

web: uvicorn src.app:app --host 0.0.0.0 --port $PORT

Hugging Face Spaces deploy

This repo is now configured for a Docker Space:

  • —Dockerfile starts the FastAPI app on port 7860
  • —README.md includes the Hugging Face Space metadata

Create the Space

  1. 1.Go to Hugging Face Spaces.
  2. 2.Choose:
  3. 3.Owner: your account
  4. 4.Space name: movie-songs-demo
  5. 5.SDK: Docker
  6. 6.Visibility: Public or Private
  7. 7.Create the Space.

Push this repo to the Space

If your Hugging Face username is asricka, run:

bash
git -C /Users/abdel/Documents/Playground remote add hf https://huggingface.co/spaces/asricka/movie-songs-demo
git -C /Users/abdel/Documents/Playground push hf main

If you already added an hf remote before, update it instead:

bash
git -C /Users/abdel/Documents/Playground remote set-url hf https://huggingface.co/spaces/asricka/movie-songs-demo
git -C /Users/abdel/Documents/Playground push hf main

You will be prompted for Hugging Face credentials or a token. After the build finishes, the Space URL will be:

https://huggingface.co/spaces/asricka/movie-songs-demo

GitHub push

After adding your remote:

bash
git push -u origin main

If your default branch is master, push that instead:

bash
git push -u origin master