Tunebat.DotNet 1.0.0-beta.1

TunebatPlatform .NET SDK

The official .NET SDK for integrating with the Tunebat Platform - a comprehensive audio processing and analysis service. This SDK provides easy-to-use APIs for audio analysis, mastering, stem separation, lyric extraction, and advanced audio visualization.

Features

• Audio Analysis - Extract musical characteristics including key, BPM, energy, danceability, and happiness metrics
• Audio Mastering - Professional mastering with reference-based processing
• Stem Separation - Extract individual instruments (vocals, drums, bass, etc.) from mixed audio
• Lyric Extraction - Extract time-synchronized lyrics with precise timestamps
• Audio Visualization - Create stunning music videos with customizable visualizers and effects

Installation

Install the SDK via NuGet:

dotnet add package Tunebat.DotNet

Or add to your .csproj file:

<PackageReference Include="Tunebat.DotNet" Version="1.0.0" />

Requirements

• .NET 8.0 or later
• Valid Tunebat Platform API access token
• HTTP/HTTPS connectivity

Quick Start

using TunebatPlatform.DotNetSdk;
using TunebatPlatform.DotNetSdk.Services.AudioAnalysis;

// Initialize the client
var httpClient = new HttpClient();
var client = new TunebatPlatformClient(
    "https://api.tunebat.com", 
    "your-access-token", 
    httpClient
);

// Analyze audio files
var settings = new AudioAnalysisSettings
{
    Files = new[]
    {
        new RemoteMediaFile
        {
            Url = "https://example.com/song.mp3",
            FileName = "song.mp3",
            FileExtension = ".mp3"
        }
    }
};

// Enqueue the job (all operations are asynchronous)
var jobId = await client.EnqueueAudioAnalysisJobAsync(
    settings, 
    "https://your-app.com/webhook/callback"
);

// The platform will POST status updates to your callback URL
// Final result will include musical analysis data

API Overview

Authentication

The SDK uses JWT Bearer token authentication. Obtain an access token from the Tunebat Platform and pass it when creating the client:

var client = new TunebatPlatformClient(baseUrl, accessToken, httpClient);

Job-Based Processing

All operations are processed asynchronously as jobs. The typical workflow is:

1. Submit a job with your settings and a callback URL
2. Receive a job ID for tracking
3. The platform POSTs status updates to your callback URL
4. Process the final result when the job completes

Callback Handling

Set up an endpoint to receive job status updates:

[HttpPost("webhook/callback")]
public IActionResult HandleCallback([FromBody] JobStatusPayload<AudioAnalysisResult> status)
{
    switch (status.Status)
    {
        case JobStatus.Completed:
            var result = status.Result;
            // Process successful result
            break;
        case JobStatus.Failed:
            // Handle failure
            break;
        case JobStatus.InProgress:
            // Track progress: status.Progress (0-100)
            break;
    }
    return Ok();
}

Services

Audio Analysis

Extract musical characteristics from audio files:

var settings = new AudioAnalysisSettings
{
    Files = new[] { new RemoteMediaFile { Url = "...", FileName = "...", FileExtension = "..." } }
};

var jobId = await client.EnqueueAudioAnalysisJobAsync(settings, callbackUrl);

// Result includes:
// - Key (e.g., "C Major", "A Minor")
// - Alternative keys (Camelot notation)
// - BPM (tempo)
// - Energy (0-1)
// - Danceability (0-1)
// - Happiness (0-1)

Audio Mastering

Apply professional mastering using a reference track:

var settings = new AudioMasteringSettings
{
    InputFile = new RemoteMediaFile { /* ... */ },
    ReferenceFile = new RemoteMediaFile { /* ... */ },
    OutputFile = new RemoteMediaFile { /* ... */ }
};

var jobId = await client.EnqueueAudioMasteringJobAsync(settings, callbackUrl);

Stem Separation

Extract individual instruments from mixed audio:

var settings = new AudioSeparationSettings
{
    InputFile = new RemoteMediaFile { /* ... */ },
    StemType = StemType.Vocal, // or Instrumental, Drum, Bass, Other
    StemOutputFile = new RemoteMediaFile { /* ... */ },
    RemnantOutputFile = new RemoteMediaFile { /* ... */ }
};

var jobId = await client.EnqueueAudioSeparationJobAsync(settings, callbackUrl);

Lyric Extraction

Extract time-synchronized lyrics:

var settings = new LyricExtractionSettings
{
    InputFile = new RemoteMediaFile { /* ... */ }
};

var jobId = await client.EnqueueLyricExtractionJobAsync(settings, callbackUrl);

// Result includes array of:
// - Text (lyric segment)
// - StartTime (TimeSpan)
// - EndTime (TimeSpan)

Audio Visualization

Create advanced music videos with customizable visualizers:

var settings = new AudioVisualizationSettings
{
    InputFile = new RemoteMediaFile { /* ... */ },
    OutputFile = new RemoteMediaFile { /* ... */ },
    AspectRatio = VideoAspectRatio.Landscape,
    
    Visualizer = new AudioVisualizerSettings
    {
        Shape = VisualizerShape.CircularBars,
        ColorHexCode = "#FF6B6B",
        EnableGlowEffect = true,
        EnableParticles = true
    },
    
    Background = new BackgroundSettings
    {
        MediaFile = new RemoteMediaFile { /* background image/video */ },
        EnableReflection = true,
        ReflectionMode = ReflectionMode.Floor
    },
    
    Export = new ExportSettings
    {
        VideoWidth = 1920,
        VideoHeight = 1080,
        FrameRate = 30,
        ConstantRateFactor = 23 // Quality (0-51, lower = better)
    }
};

var jobId = await client.EnqueueAudioVisualizationJobAsync(settings, callbackUrl);

Error Handling

The SDK provides detailed error information through TunebatPlatformApiException:

try
{
    var jobId = await client.EnqueueAudioAnalysisJobAsync(settings, callbackUrl);
}
catch (TunebatPlatformApiException ex)
{
    Console.WriteLine($"API Error: {ex.Message}");
    Console.WriteLine($"Status Code: {ex.StatusCode}");
    Console.WriteLine($"Response: {ex.ResponseContent}");
    
    // Validation errors are included if applicable
    foreach (var error in ex.ValidationErrors)
    {
        Console.WriteLine($"Field: {error.Key}, Errors: {string.Join(", ", error.Value)}");
    }
}

Advanced Configuration

Custom HTTP Client

You can provide a configured HttpClient for advanced scenarios:

var httpClient = new HttpClient
{
    Timeout = TimeSpan.FromMinutes(5)
};

// Add custom headers, handlers, etc.
httpClient.DefaultRequestHeaders.Add("X-Custom-Header", "value");

var client = new TunebatPlatformClient(baseUrl, accessToken, httpClient);

Validation

All settings are validated before sending to the API. The SDK uses FluentValidation to ensure your requests meet requirements:

// Example: This will throw validation exception
var settings = new AudioAnalysisSettings
{
    Files = Array.Empty<RemoteMediaFile>() // Files are required
};

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This SDK is provided under the MIT License. See LICENSE file for details.

Support

For support, please contact support@tunebat.com or visit our documentation.