TimbreSpace SDK

A Python SDK for interacting with the TimbreSpace API.

Installation

pip install timbrespace-sdk

Development Setup

We recommend using uv for fast, modern Python dependency management and testing.

Install dependencies

uv pip install -r requirements.txt

Run tests

uv pip install --system -r requirements.txt  # if not already installed
uv pip install --system -r requirements-dev.txt  # if you have dev requirements
uv pytest

Running Tests Easily

You can use the provided scripts to run all tests with one command:

On Mac/Linux:

./run-tests.sh

You can also pass any extra pytest arguments to these scripts, for example:

./run-tests.sh -k test_audio_analyze

Usage

Authentication

from timbrespace_sdk import TimbreSpaceClient

# Initialize with API key
client = TimbreSpaceClient(api_url="https://api.timbrespace.app", api_key="your_api_key")

# Get current user info
user = await client.user.get_current_user()
print(f"Logged in as: {user.email}")

# List all your API keys
api_keys = await client.user.get_api_keys()

Working with Audio Samples

# Create an audio sample
sample = await client.samples.


# Get audio samples
samples = await client.samples.get_samples(limit=10)
sample = await client.samples.get_sample("sample_id")

# Analyze audio sample
analysis = await client.samples.analyze_sample("sample_id")
properties = await client.samples.get_technical_properties("sample_id")

# Time-based analysis
windows = await client.samples.compute_windows(
    "sample_id",
    window_size=2048,
    hop_size=1024
)

# Semantic search for audio samples
results = await client.samples.search_samples("bright synth lead", limit=5)

# Audio sample embeddings
embedding = await client.samples.embed_sample("sample_id", model="clap")
similar = await client.samples.get_similar_samples("sample_id", limit=5)

# Batch operations
await client.samples.embed_samples_batch(["sample_id1", "sample_id2"], model="clap")

Working with Audio Files

# Placeholder for future audio file operations
# client.audio will provide methods for uploading, listing, and analyzing raw audio files

Working with Sample Packs

# Get and search sample packs
packs = await client.samplepacks.get_samplepacks(
    limit=10,
    genre="electronic",
    category="drums"
)
search_results = await client.samplepacks.search_samplepacks("analog drums")

# Get specific sample pack with details
pack = await client.samplepacks.get_samplepack("pack_id")

# Get samples in a pack
samples = await client.samplepacks.get_samplepack_samples("pack_id")

# Create a new sample pack
new_pack = await client.samplepacks.create_samplepack(
    name="My Awesome Pack",
    description="A collection of amazing sounds",
    resource_ids=["resource_id1", "resource_id2"],
    genre="electronic",
    category="synths",
    tags=["analog", "warm", "vintage"]
)

# Analyze a sample pack
await client.samplepacks.analyze_samplepack("pack_id")

# Delete a sample pack
await client.samplepacks.delete_samplepack("pack_id")

Working with Resources

# Get resources
resources = await client.resources.get_resources()

# Create a resource from a local file
resource = await client.resources.create_resource(
    file="path/to/file.wav",
    category="audio_sample",
    name="My Audio File",
    is_public=False
)

# Create a resource from a URL
resource = await client.resources.create_resource_from_url(
    url="https://example.com/audio.wav",
    category="audio_sample", 
    name="Audio from URL",
    is_public=False,
    tags=["web", "download"],
    wait_for_ingestion=False
)

# Get a specific resource
resource = await client.resources.get_resource("resource_id")

# Trigger resource ingestion/processing
await client.resources.ingest_resource("resource_id")

Modules

The SDK is organized into modules:

• user: Authentication and API key management
• samples: Working with audio samples and analysis
• audio: Working with audio files (future)
• samplepacks: Managing sample packs
• embeddings: Creating and working with audio embeddings
• resources: Managing resources (files)

Error Handling

from timbrespace_sdk.errors import TimbreSpaceAPIError

try:
    samples = await client.samples.get_samples()
except TimbreSpaceAPIError as e:
    print(f"API Error: {e.status_code} - {e.detail}")
except Exception as e:
    print(f"Error: {str(e)}")

Documentation

For full documentation, visit docs.timbrespace.com.

Examples

See the examples/ directory for more usage examples.