# Ultimate Guitar Scraper

Python library to download your favorited tabs from Ultimate-Guitar.com.

[![PyPI version](https://badge.fury.io/py/ultimate-guitar-scraper.svg)](https://pypi.org/project/ultimate-guitar-scraper/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/ultimate-guitar-scraper)](https://pypi.org/project/ultimate-guitar-scraper/)

## What Works

- **Favorites**: Download all your liked tabs (requires cookies)
- **Tab Content**: Get individual tab content by URL

## What Doesn't Work Yet

**Search is broken.** Cloudflare blocks automated searches pretty consistently. If you want to help fix this, PRs are welcome. For now, use the UG website to find tabs, favorite them, then use this to download.

## Installation

### From PyPI (recommended)

```bash
pip install ultimate-guitar-scraper
```

For Cloudflare bypass support:
```bash
pip install ultimate-guitar-scraper[cloudflare]
```

### From source

```bash
git clone https://github.com/yourusername/ug_api.git
cd ug_api
pip install -e .
```

## Usage

Get your cookies from browser DevTools (F12 → Application → Cookies → ultimate-guitar.com). You need `SESSIONUG` and `bbsessionhash`.

```python
from ug_api import UGScraper

cookies = {
    'SESSIONUG': 'your_session_cookie_here',
    'bbsessionhash': 'your_bb_session_here'
}

scraper = UGScraper(cookies)

# Get your favorites
result = scraper.get_favorites()
for tab in result['favorites']:
    print(f"{tab['artist']} - {tab['title']} ({tab['type']})")
    print(f"  URL: {tab['url']}")

# Download a specific tab
tab = scraper.get_tab("https://tabs.ultimate-guitar.com/tab/...")
if not tab['error']:
    print(tab['content'])
```

## How to Get Cookies

1. Open Ultimate-Guitar.com in your browser
2. Log in
3. Press F12 to open DevTools
4. Go to Application tab → Cookies → ultimate-guitar.com
5. Copy the values for `SESSIONUG` and `bbsessionhash`
6. Paste them into the cookies dict

## API

### `UGScraper(cookies)`

Initialize with your UG session cookies.

**Args:**
- `cookies` (dict): Your UG cookies including SESSIONUG and bbsessionhash

### `get_favorites()`

Get all your favorited tabs.

**Returns:**
```python
{
    'favorites': [
        {
            'title': 'Song Name',
            'artist': 'Artist Name',
            'type': 'Chords',
            'url': 'https://...',
            'liked_at': '2024-01-01'
        }
    ],
    'error': None
}
```

### `get_tab(url)`

Download tab content from a URL.

**Returns:**
```python
{
    'title': 'Song Name',
    'artist': 'Artist Name',
    'content': '...',
    'url': 'https://...',
    'error': None
}
```

## Known Issues

- **No search**: Cloudflare blocks search requests. Favorite tabs manually on the website first.
- **Official tabs**: Can't download official/licensed tabs
- **Rate limiting**: Use cookies to avoid getting blocked

## Contributing

Search functionality needs work. If you figure out a way around Cloudflare's bot detection, please submit a PR.

## Publishing to PyPI

To publish this package:

```bash
# Install build tools
pip install build twine

# Build the package
python -m build

# Upload to PyPI (you'll need PyPI account credentials)
python -m twine upload dist/*
```

For TestPyPI (testing):
```bash
python -m twine upload --repository testpypi dist/*
```

## License

AGPL-3.0-or-later - Educational use only. Respect UG's ToS.
