# spotify-python

**Repository Path**: cnull_project/spotify-python

## Basic Information

- **Project Name**: spotify-python
- **Description**: 1232132131312
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spotify Track Lookup

This project searches Spotify by song name, optionally filters by artist name,
and then enriches the matched track with MusicBrainz metadata.

The script outputs JSON with these top-level track fields:

- `name`
- `artist`
- `album`
- `spotify_url`
- `spotify_uri`
- `track_number`
- `album_total_tracks`
- `release_date`
- `genres`
- `isrc`
- `label`
- `composer`
- `cover_url`
- `album_info`
- `artists_info`
- `musicbrainz`

## Project Files

Main files:

- `spotify_track_lookup.py`
- `python-runtime/`
- `environment.yml`

Notes:

- `spotify_track_lookup.py` is the main entry script.
- `python-runtime/` is the bundled local Python runtime for this project.
- `environment.yml` is kept only as a rebuild reference.

## Bundled Runtime

This project already includes a self-contained local runtime in
`python-runtime/`.

You do not need to create or activate a separate conda environment just to run
the script in this folder.

Run it directly:

```powershell
.\python-runtime\python.exe spotify_track_lookup.py "Believer"
```

With artist filter:

```powershell
.\python-runtime\python.exe spotify_track_lookup.py "Qi Li Xiang" --artist "Jay Chou"
```

## Clean Machine Deployment

Use this workflow on a new computer that has not run this project before.

### 1. Prerequisites

Install:

- `Miniconda` or `Anaconda`
- `Google Chrome` or `Microsoft Edge`

Make sure the machine can reach:

- `open.spotify.com`
- `musicbrainz.org`

Notes:

- Spotify search is fetched through Selenium in headless browser mode.
- In most cases you do not need to install `chromedriver` or `msedgedriver`
  manually. Selenium will use the local browser and resolve the driver.

### 2. Copy or Clone the Project

Clone with Git:

```powershell
git clone <your-repo-url> spotify-python
cd spotify-python
```

Or copy the whole project directory to the new machine. If you copy files
manually, keep at least these paths:

- `spotify_track_lookup.py`
- `python-runtime/`
- `README.md`

### 3. Run with the Bundled Runtime

Run:

```powershell
.\python-runtime\python.exe spotify_track_lookup.py "Believer"
```

### 4. Verify the Installation

```powershell
.\python-runtime\python.exe spotify_track_lookup.py --help
```

If help text prints successfully, the environment is ready.

### 5. Optional: Rebuild the Runtime Yourself

If you do not want to use the bundled runtime, you can still rebuild from
`environment.yml` in a separate conda environment.

## Command Line Usage

With artist filter:

```powershell
.\python-runtime\python.exe spotify_track_lookup.py "Qi Li Xiang" --artist "Jay Chou"
```

Without artist filter:

```powershell
.\python-runtime\python.exe spotify_track_lookup.py "Believer"
```

Save output to a file:

```powershell
.\python-runtime\python.exe spotify_track_lookup.py "Believer" > result.json
```

The script prints JSON to stdout.

## Call from Another Python Program

The simplest stable integration is to call the script as a subprocess and parse
its JSON output:

```python
import json
import subprocess
import sys

cmd = [
    sys.executable,
    "spotify_track_lookup.py",
    "Qi Li Xiang",
    "--artist",
    "Jay Chou",
]

result = subprocess.run(cmd, capture_output=True, text=True, check=True)
data = json.loads(result.stdout)

print(data["track"]["artist"])
print(data["track"]["cover_url"])
```

## Output Schema

```json
{
  "query": {
    "song_name": "string",
    "artist": "string | null"
  },
  "track": {
    "name": "string",
    "artist": "string",
    "album": "string | null",
    "spotify_url": "string",
    "spotify_uri": "string | null",
    "track_number": "number | null",
    "album_total_tracks": "number | null",
    "release_date": "string | null",
    "genres": ["string"],
    "isrc": ["string"],
    "label": ["string"],
    "composer": ["string"],
    "cover_url": "string | null",
    "album_info": {
      "name": "string | null",
      "spotify_url": "string | null",
      "spotify_uri": "string | null",
      "artists": ["string"],
      "total_tracks": "number | null",
      "cover_url": "string | null"
    },
    "artists_info": [
      {
        "name": "string",
        "spotify_url": "string",
        "spotify_uri": "string | null",
        "followers": "number | null",
        "monthly_listeners": "number | null",
        "image_url": "string | null",
        "genres": ["string"]
      }
    ],
    "musicbrainz": {
      "recording_id": "string | null",
      "release_id": "string | null",
      "error": "string | null"
    }
  }
}
```

## Example Output

Command:

```powershell
python spotify_track_lookup.py "Qi Li Xiang" --artist "Jay Chou"
```

Example:

```json
{
  "query": {
    "song_name": "Qi Li Xiang",
    "artist": "Jay Chou"
  },
  "track": {
    "name": "Qi Li Xiang",
    "artist": "Jay Chou",
    "album": "Qi Li Xiang",
    "spotify_url": "https://open.spotify.com/track/57w29bSwdIZ6gr6xXOqwc1",
    "spotify_uri": "spotify:track:57w29bSwdIZ6gr6xXOqwc1",
    "track_number": 2,
    "album_total_tracks": 10,
    "release_date": "2004-08-03",
    "genres": [
      "Mandopop"
    ],
    "isrc": [
      "TWC230400702",
      "TWK970400702"
    ],
    "label": [],
    "composer": [
      "Jay Chou"
    ],
    "cover_url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b273d6dbe22a1e76bce856461820"
  }
}
```

## Data Sources

- Spotify search page
- Spotify embedded page state
- `SpotifyScraper`
- MusicBrainz API
- iTunes Artist Search

In practice:

- `cover_url`, album, track numbers, and release date mainly come from Spotify
- `isrc`, `label`, and `composer` mainly come from MusicBrainz
- `genres` prefer Spotify and artist data, with iTunes as fallback

## Troubleshooting

### `ModuleNotFoundError: No module named 'selenium'`

The conda environment is probably not active:

```powershell
conda activate spotify-scraper
```

### Browser launch fails

Install at least one of these:

- Chrome
- Edge

### Spotify search times out or returns nothing

Check:

- access to `open.spotify.com`
- proxy or firewall settings
- whether the song name is too ambiguous

### `label` or `isrc` is empty

This is normal for some MusicBrainz releases or recordings.

## Recommended Deployment Pattern

If you need to hand this project to another person or move it to multiple
machines, package the whole project directory and have them run:

```powershell
.\python-runtime\python.exe spotify_track_lookup.py "Believer"
```

Then call:

```powershell
.\python-runtime\python.exe spotify_track_lookup.py "Qi Li Xiang" --artist "Jay Chou"
```