A comprehensive Python client library for a music streaming API. This library provides both programmatic access and command-line interface (CLI) for interacting with songbox's music platform.

Features

🔐 Authentication: Login with mobile number and OTP verification
👤 User Management: Get user profile, following lists, and user operations
🎵 Music Operations: Search songs, get albums, artists, and trending music
🖥️ CLI Support: Full command-line interface for all operations
🔧 Modular Design: Separate clients for different API categories
📦 Easy Installation: Simple pip install with all dependencies
🛡️ Error Handling: Comprehensive exception handling with meaningful errors

Installation

pip install songbox

Or install from source:

git clone https://github.com/yourusername/songbox.git
cd songbox
pip install -e .

Quick Start

Python Library Usage

from songbox import songboxClient

# Create client
client = songboxClient()

# Authenticate
verify_id = client.auth.login("960", "7777777")
opt_code = input("Enter OTP: ")
token = client.auth.verify_otp(otp_code, verify_id)

# Get user info
user_info = client.user.get_me()
print(f"Welcome, {user_info['username']}!")

# Search for music
results = client.music.search("huttaa")
for category in results:
    print(f"Category: {category['title']}")
    for item in category['items']:
        print(f"  - {item['heading']} by {item['sub_heading']}")

# Get album details
album = client.music.get_album("808")
print(f"Album: {album['name']} by {album['artist_name']}")
print(f"Songs: {len(album['songs'])}")

# Close client when done
client.close()

CLI Usage

# Login
songbox auth login --country-code 960 --mobile 7777777
songbox auth verify --otp 123456 --verify-id <verify_id>

# Set token for subsequent commands
export songbox_TOKEN="your_jwt_token_here"

# Get user info
songbox user me

# Search for music
songbox music search "huttaa"

# Get album information
songbox music album 808

# Get trending music
songbox music trending --limit 10

# Different output formats
songbox music search "huttaa" --format json
songbox user me --format table

API Reference

Authentication (`client.auth`)

login(country_code, mobile_number) - Initiate login with mobile number
verify_otp(otp, verify_id) - Verify OTP and get authentication token
refresh_token() - Refresh the current authentication token
logout() - Clear authentication token
get_token_info() - Get information about current token

User Management (`client.user`)

get_me() - Get current user's profile information
get_following() - Get list of followed users/artists
get_user_profile(user_id) - Get profile of specific user
follow_user(user_id) - Follow a user or artist
unfollow_user(user_id) - Unfollow a user or artist
update_profile(**kwargs) - Update current user's profile

Music Operations (`client.music`)

search(query) - Search for songs, artists, and albums
get_album(album_id) - Get detailed album information
get_song(song_id) - Get detailed song information
get_artist(artist_id) - Get detailed artist information
get_recommendations(limit=None) - Get personalized recommendations
get_playlists() - Get user's playlists

Configuration

Environment Variables

songbox_TOKEN - Authentication token for CLI usage

Client Configuration

client = songboxClient(
    timeout=30.0,  # Request timeout in seconds
    headers={"Custom-Header": "value"}  # Additional headers
)

Error Handling

The library provides specific exceptions for different error types:

from songbox.exceptions import (
    songboxError,
    AuthenticationError,
    APIError,
    NotFoundError,
    ValidationError
)

try:
    user_info = client.user.get_me()
except AuthenticationError:
    print("Please login first")
except NotFoundError:
    print("User not found")
except APIError as e:
    print(f"API Error: {e.message} (Status: {e.status_code})")
except songboxError as e:
    print(f"General error: {e}")

CLI Commands

Authentication Commands

songbox auth login --country-code <code> --mobile <number>
songbox auth verify --otp <otp> --verify-id <verify_id>
songbox auth refresh
songbox auth logout

User Commands

songbox user me
songbox user following

Music Commands

songbox music search <query>
songbox music album <album_id>
songbox music song <song_id>
songbox music artist <artist_id>
songbox music trending [--limit <number>]

Output Formats

--format simple (default) - Human-readable format
--format json - JSON output
--format table - Tabular format

Examples

Complete Authentication Flow

from songbox import songboxClient
from songbox.exceptions import AuthenticationError

client = songboxClient()

try:
    # Step 1: Initiate login
    verify_id = client.auth.login("960", "7777777")
    print(f"OTP sent! Verification ID: {verify_id}")
    
    # Step 2: Get OTP from user
    otp = input("Enter OTP: ")
    
    # Step 3: Verify OTP and get token
    token = client.auth.verify_otp(otp, verify_id)
    print(f"Login successful! Token: {token}")
    
    # Step 4: Use the API
    user_info = client.user.get_me()
    print(f"Welcome, {user_info['username']}!")
    
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
finally:
    client.close()

Music Discovery

# Search and explore music
results = client.music.search("maldivian music")

for category in results:
    print(f"\n{category['title']}:")
    for item in category['items'][:3]:  # Show top 3
        print(f"  {item['heading']} - {item['sub_heading']}")
        
        # Get detailed info if it's a song
        if category['title'] == 'Songs':
            try:
                song_details = client.music.get_song(item['destination_id'])
                print(f"    Duration: {song_details.get('duration', 'Unknown')}s")
            except:
                pass

Development

Setting up for Development

git clone https://github.com/yourusername/songbox.git
cd songbox
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

black songbox/
flake8 songbox/
mypy songbox/

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: This is an unofficial client library. songbox is a trademark of its respective owners.

README.md

API Client Library