audial-sdk 1.0.0__tar.gz

audial_sdk-1.0.0/API_DOCUMENTATION.md

@@ -0,0 +1,731 @@
+# Audial SDK API Documentation
+
+This document provides comprehensive documentation for the Audial SDK, including detailed information about all functions, parameters, return values, and examples for both the Python API and Command Line Interface (CLI).
+
+## Table of Contents
+
+- [Python API](#python-api)
+  - [Configuration](#configuration)
+  - [Stem Splitting](#stem-splitting)
+  - [Audio Analysis](#audio-analysis)
+  - [Audio Segmentation](#audio-segmentation)
+  - [Audio Mastering](#audio-mastering)
+  - [Sample Pack Generation](#sample-pack-generation)
+  - [MIDI Generation](#midi-generation)
+  - [Error Handling](#error-handling)
+- [Command Line Interface](#command-line-interface)
+  - [Configuration Commands](#configuration-commands)
+  - [Stem Splitting Commands](#stem-splitting-commands)
+  - [Audio Analysis Commands](#audio-analysis-commands)
+  - [Audio Segmentation Commands](#audio-segmentation-commands)
+  - [Audio Mastering Commands](#audio-mastering-commands)
+  - [Sample Pack Generation Commands](#sample-pack-generation-commands)
+  - [MIDI Generation Commands](#midi-generation-commands)
+- [Result Data Structure](#result-data-structure)
+
+## Python API
+
+### Configuration
+
+#### Setting API Key and User ID
+
+```python
+import audial
+
+# Set API key
+audial.config.set_api_key("your_api_key_here")
+
+# Set User ID
+audial.config.set_user_id("your_user_id_here")
+
+# Get current API key and User ID
+api_key = audial.config.get_api_key()
+user_id = audial.config.get_user_id()
+```
+
+#### Setting Results Folder
+
+```python
+# Set custom results folder
+audial.config.set_results_folder("path/to/custom/folder")
+
+# Get current results folder
+results_folder = audial.config.get_results_folder()
+```
+
+### Stem Splitting
+
+Split an audio track into its component parts.
+
+#### Function Signature
+
+```python
+audial.stem_split(
+    file_path: str,
+    stems: Optional[List[str]] = None,
+    target_bpm: Optional[float] = None,
+    target_key: Optional[str] = None,
+    results_folder: Optional[str] = None,
+    api_key: Optional[str] = None,
+    algorithm: str = "primaudio"
+) -> Dict[str, Any]
+```
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_path` | str | Yes | - | Path to the audio file to process |
+| `stems` | List[str] | No | `["vocals", "drums", "bass", "other"]` | List of stems to extract |
+| `target_bpm` | float | No | `None` | Target BPM for tempo adjustment |
+| `target_key` | str | No | `None` | Target key for pitch adjustment (e.g., "Cmaj", "Dmin") |
+| `results_folder` | str | No | `None` | Folder to save results (uses default if `None`) |
+| `api_key` | str | No | `None` | API key to use (uses default if `None`) |
+| `algorithm` | str | No | `"primaudio"` | Algorithm to use (`"primaudio"` or `"quintessound"`) |
+
+#### Available Stem Options
+
+- `vocals` - Vocal track
+- `drums` - Drum track
+- `bass` - Bass track
+- `other` - All other instruments
+- `full_song_without_vocals` - Full mix minus vocals
+- `full_song_without_drums` - Full mix minus drums
+- `full_song_without_bass` - Full mix minus bass
+- `full_song_without_other` - Full mix minus other instruments
+
+#### Returns
+
+A dictionary containing:
+- `execution`: API response data
+- `files`: Information about downloaded files
+  - `folder`: Path to the results folder
+  - `files`: Dictionary mapping filenames to local file paths
+
+#### Example
+
+```python
+import audial
+
+# Basic stem splitting
+result = audial.stem_split("path/to/audio.mp3")
+
+# Access the paths to the downloaded files
+stems_folder = result["files"]["folder"]
+vocals_path = result["files"]["files"]["vocals.mp3"]
+drums_path = result["files"]["files"]["drums.mp3"]
+bass_path = result["files"]["files"]["bass.mp3"]
+other_path = result["files"]["files"]["other.mp3"]
+
+# Advanced stem splitting with options
+result = audial.stem_split(
+    "path/to/audio.mp3",
+    stems=["vocals", "drums", "full_song_without_vocals"],
+    target_bpm=120,
+    target_key="Cmaj",
+    algorithm="primaudio"
+)
+```
+
+### Audio Analysis
+
+Analyze an audio file to extract metadata like BPM, key, and other characteristics.
+
+#### Function Signature
+
+```python
+audial.analyze(
+    file_path: str,
+    results_folder: Optional[str] = None,
+    api_key: Optional[str] = None
+) -> Dict[str, Any]
+```
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_path` | str | Yes | - | Path to the audio file to analyze |
+| `results_folder` | str | No | `None` | Folder to save results (uses default if `None`) |
+| `api_key` | str | No | `None` | API key to use (uses default if `None`) |
+
+#### Returns
+
+A dictionary containing:
+- `execution`: API response data
+- `analysis`: Analysis results including BPM, key, and other metadata
+- `files`: Information about downloaded files
+  - `folder`: Path to the results folder
+  - `files`: Dictionary mapping filenames to local file paths
+
+#### Example
+
+```python
+import audial
+
+# Analyze an audio file
+analysis = audial.analyze("path/to/audio.mp3")
+
+# Access analysis results
+bpm = analysis["analysis"]["bpm"]
+key = analysis["analysis"]["key"]
+
+print(f"BPM: {bpm}")
+print(f"Key: {key}")
+```
+
+### Audio Segmentation
+
+Segment an audio track into logical sections and analyze its components.
+
+#### Function Signature
+
+```python
+audial.segment(
+    file_path: str,
+    components: Optional[List[str]] = None,
+    analysis_type: Optional[str] = None,
+    features: Optional[List[str]] = None,
+    genre: Optional[str] = None,
+    results_folder: Optional[str] = None,
+    api_key: Optional[str] = None
+) -> Dict[str, Any]
+```
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_path` | str | Yes | - | Path to the audio file to segment |
+| `components` | List[str] | No | `["bass", "beat", "melody", "vocal"]` | Components to segment |
+| `analysis_type` | str | No | `"select_features"` | Type of analysis to perform |
+| `features` | List[str] | No | `["mode", "energy", "loudness", "danceability", "tatum", "lyrics", "tags"]` | Features to extract |
+| `genre` | str | No | `"Default"` | Genre of the track |
+| `results_folder` | str | No | `None` | Folder to save results (uses default if `None`) |
+| `api_key` | str | No | `None` | API key to use (uses default if `None`) |
+
+#### Available Features
+
+- `mode` - Musical mode
+- `energy` - Energy level
+- `loudness` - Loudness level
+- `danceability` - Danceability rating
+- `tatum` - Tatum features
+- `lyrics` - Lyrics detection
+- `key` - Musical key
+- `tags` - Audio tags
+
+#### Available Genres
+
+`"Default"`, `"Afro House"`, `"Tech House"`, `"Bass House"`, `"Blues"`, `"Breakbeat"`, `"Classic Rock"`, `"Country"`, `"Deep House"`, `"Drum N Bass"`, `"Dubstep"`, `"Gospel"`, `"Grime140"`, `"House"`, `"Indie"`, `"Jazz"`, `"Latin"`, `"Metal"`, `"Minimal House"`, `"Pop"`, `"R&B"`, `"Rock"`, `"Techno"`, `"Trance"`, `"Trap"`, `"UK Garage"`
+
+#### Returns
+
+A dictionary containing:
+- `execution`: API response data
+- `segmentation`: Segmentation data (if available)
+- `files`: Information about downloaded files
+  - `folder`: Path to the results folder
+  - `files`: Dictionary mapping filenames to local file paths
+
+#### Example
+
+```python
+import audial
+
+# Basic segmentation
+segments = audial.segment("path/to/audio.mp3")
+
+# Advanced segmentation with options
+segments = audial.segment(
+    "path/to/audio.mp3",
+    components=["bass", "beat", "melody", "vocal"],
+    analysis_type="select_features",
+    features=["energy", "loudness", "danceability", "tatum"],
+    genre="Tech House"
+)
+
+# Access segmentation files
+json_file = segments["files"]["files"].get("audio_segmentation.json")
+```
+
+### Audio Mastering
+
+Apply professional mastering to an audio file.
+
+#### Function Signature
+
+```python
+audial.master(
+    file_path: str,
+    reference_file: Optional[str] = None,
+    results_folder: Optional[str] = None,
+    api_key: Optional[str] = None
+) -> Dict[str, Any]
+```
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_path` | str | Yes | - | Path to the audio file to master |
+| `reference_file` | str | No | `None` | Path to a reference file to match sound characteristics |
+| `results_folder` | str | No | `None` | Folder to save results (uses default if `None`) |
+| `api_key` | str | No | `None` | API key to use (uses default if `None`) |
+
+#### Returns
+
+A dictionary containing:
+- `execution`: API response data
+- `files`: Information about downloaded files
+  - `folder`: Path to the results folder
+  - `files`: Dictionary mapping filenames to local file paths
+
+#### Example
+
+```python
+import audial
+
+# Basic mastering
+mastered = audial.master("path/to/audio.mp3")
+
+# Mastering with reference track
+mastered = audial.master(
+    "path/to/audio.mp3",
+    reference_file="path/to/reference.mp3"
+)
+
+# Get the path to the mastered file
+master_file = next(iter(mastered["files"]["files"].values()))
+```
+
+### Sample Pack Generation
+
+Generate a sample pack from an audio file.
+
+#### Function Signature
+
+```python
+audial.generate_samples(
+    file_path: str,
+    job_type: Optional[str] = None,
+    components: Optional[List[str]] = None,
+    genre: Optional[str] = None,
+    results_folder: Optional[str] = None,
+    api_key: Optional[str] = None
+) -> Dict[str, Any]
+```
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_path` | str | Yes | - | Path to the audio file |
+| `job_type` | str | No | `"sample_pack"` | Type of sample pack job to run |
+| `components` | List[str] | No | `["drums", "bass", "melody"]` | Components to include in the sample pack |
+| `genre` | str | No | `"Default"` | Genre of the track |
+| `results_folder` | str | No | `None` | Folder to save results (uses default if `None`) |
+| `api_key` | str | No | `None` | API key to use (uses default if `None`) |
+
+#### Available Components
+
+- `drums` - Drum samples
+- `bass` - Bass samples
+- `melody` - Melodic samples
+
+#### Available Genres
+
+Same as [Audio Segmentation](#audio-segmentation).
+
+#### Returns
+
+A dictionary containing:
+- `execution`: API response data
+- `files`: Information about downloaded files
+  - `folder`: Path to the results folder
+  - `files`: Dictionary mapping filenames to local file paths
+
+#### Example
+
+```python
+import audial
+
+# Basic sample pack generation
+samples = audial.generate_samples("path/to/audio.mp3")
+
+# Advanced sample pack generation with options
+samples = audial.generate_samples(
+    "path/to/audio.mp3",
+    job_type="sample_pack",
+    components=["drums", "bass", "melody"],
+    genre="Tech House"
+)
+
+# Access the sample pack folder
+samples_folder = samples["files"]["folder"]
+
+# List all downloaded samples
+for sample_name, sample_path in samples["files"]["files"].items():
+    print(f"{sample_name}: {sample_path}")
+```
+
+### MIDI Generation
+
+Convert audio to MIDI data.
+
+#### Function Signature
+
+```python
+audial.generate_midi(
+    file_path: Union[str, List[str]],
+    bpm: Optional[float] = None,
+    results_folder: Optional[str] = None,
+    api_key: Optional[str] = None
+) -> Dict[str, Any]
+```
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_path` | str or List[str] | Yes | - | Path to one or more audio files |
+| `bpm` | float | No | `None` | Override BPM for the MIDI generation |
+| `results_folder` | str | No | `None` | Folder to save results (uses default if `None`) |
+| `api_key` | str | No | `None` | API key to use (uses default if `None`) |
+
+#### Returns
+
+A dictionary containing:
+- `execution`: API response data
+- `files`: Information about downloaded files
+  - `folder`: Path to the results folder
+  - `files`: Dictionary mapping filenames to local file paths
+
+#### Example
+
+```python
+import audial
+
+# Generate MIDI from a single file
+midi = audial.generate_midi("path/to/audio.mp3", bpm=120)
+
+# Generate MIDI from multiple files
+midi = audial.generate_midi(
+    ["path/to/file1.mp3", "path/to/file2.mp3"],
+    bpm=140
+)
+
+# Access the MIDI files
+for midi_file, file_path in midi["files"]["files"].items():
+    print(f"{midi_file}: {file_path}")
+```
+
+### Error Handling
+
+The SDK provides custom exception classes for better error handling:
+
+```python
+from audial.api.exceptions import AudialError, AudialAuthError, AudialAPIError
+
+try:
+    result = audial.stem_split("path/to/audio.mp3")
+except AudialAuthError as e:
+    print(f"Authentication error: {e}")
+    # Handle authentication issues
+except AudialAPIError as e:
+    print(f"API error: {e}")
+    # Handle API-specific issues
+except AudialError as e:
+    print(f"General error: {e}")
+    # Handle other errors
+```
+
+## Command Line Interface
+
+The Audial SDK provides a command-line interface for all its functions.
+
+### Configuration Commands
+
+#### Show Current Configuration
+
+```bash
+audial config show
+```
+
+#### Set API Key
+
+```bash
+audial config --api-key your_api_key_here
+```
+
+#### Set User ID
+
+```bash
+audial config --user-id your_user_id_here
+```
+
+#### Set Results Folder
+
+```bash
+audial config --results-folder path/to/results/folder
+```
+
+### Stem Splitting Commands
+
+#### Basic Stem Splitting
+
+```bash
+audial stem-split path/to/audio.mp3
+```
+
+#### Custom Stems
+
+```bash
+audial stem-split path/to/audio.mp3 --stems vocals,drums,bass,other
+```
+
+#### Full Song Without Specific Stems
+
+```bash
+audial stem-split path/to/audio.mp3 --stems full_song_without_vocals,full_song_without_drums
+```
+
+#### Tempo Adjustment
+
+```bash
+audial stem-split path/to/audio.mp3 --target-bpm 120
+```
+
+#### Key Adjustment
+
+```bash
+audial stem-split path/to/audio.mp3 --target-key Cmaj
+```
+
+#### Algorithm Selection
+
+```bash
+audial stem-split path/to/audio.mp3 --algorithm primaudio
+```
+
+```bash
+audial stem-split path/to/audio.mp3 --algorithm quintessound
+```
+
+#### Custom Results Folder
+
+```bash
+audial stem-split path/to/audio.mp3 --results-folder path/to/custom/folder
+```
+
+#### Custom API Key
+
+```bash
+audial stem-split path/to/audio.mp3 --api-key your_custom_api_key
+```
+
+### Audio Analysis Commands
+
+#### Basic Analysis
+
+```bash
+audial analyze path/to/audio.mp3
+```
+
+#### Custom Results Folder
+
+```bash
+audial analyze path/to/audio.mp3 --results-folder path/to/custom/folder
+```
+
+#### Custom API Key
+
+```bash
+audial analyze path/to/audio.mp3 --api-key your_custom_api_key
+```
+
+### Audio Segmentation Commands
+
+#### Basic Segmentation
+
+```bash
+audial segment path/to/audio.mp3
+```
+
+#### Custom Features
+
+```bash
+audial segment path/to/audio.mp3 --features energy,loudness,danceability,tatum
+```
+
+#### Specific Genre
+
+```bash
+audial segment path/to/audio.mp3 --genre "Tech House"
+```
+
+#### Analysis Type
+
+```bash
+audial segment path/to/audio.mp3 --analysis-type select_features
+```
+
+#### Custom Results Folder
+
+```bash
+audial segment path/to/audio.mp3 --results-folder path/to/custom/folder
+```
+
+#### Custom API Key
+
+```bash
+audial segment path/to/audio.mp3 --api-key your_custom_api_key
+```
+
+### Audio Mastering Commands
+
+#### Basic Mastering
+
+```bash
+audial master path/to/audio.mp3 --reference path/to/reference.mp3
+```
+
+Note: The reference file is required for the CLI interface.
+
+#### Custom Results Folder
+
+```bash
+audial master path/to/audio.mp3 --reference path/to/reference.mp3 --results-folder path/to/custom/folder
+```
+
+#### Custom API Key
+
+```bash
+audial master path/to/audio.mp3 --reference path/to/reference.mp3 --api-key your_custom_api_key
+```
+
+### Sample Pack Generation Commands
+
+#### Basic Sample Pack Generation
+
+```bash
+audial generate-samples path/to/audio.mp3
+```
+
+#### Custom Components
+
+```bash
+audial generate-samples path/to/audio.mp3 --components drums,bass,melody
+```
+
+#### Specific Genre
+
+```bash
+audial generate-samples path/to/audio.mp3 --genre "Tech House"
+```
+
+#### Job Type
+
+```bash
+audial generate-samples path/to/audio.mp3 --job-type sample_pack
+```
+
+#### Custom Results Folder
+
+```bash
+audial generate-samples path/to/audio.mp3 --results-folder path/to/custom/folder
+```
+
+#### Custom API Key
+
+```bash
+audial generate-samples path/to/audio.mp3 --api-key your_custom_api_key
+```
+
+### MIDI Generation Commands
+
+#### Basic MIDI Generation
+
+```bash
+audial generate-midi path/to/audio.mp3
+```
+
+#### Multiple Files
+
+```bash
+audial generate-midi path/to/file1.mp3 path/to/file2.mp3 path/to/file3.mp3
+```
+
+#### Specific BPM
+
+```bash
+audial generate-midi path/to/audio.mp3 --bpm 120
+```
+
+#### Custom Results Folder
+
+```bash
+audial generate-midi path/to/audio.mp3 --results-folder path/to/custom/folder
+```
+
+#### Custom API Key
+
+```bash
+audial generate-midi path/to/audio.mp3 --api-key your_custom_api_key
+```
+
+## Result Data Structure
+
+All functions return a consistent result structure:
+
+```python
+{
+    "execution": {
+        # Raw API response data
+        "exeId": "execution-id",
+        "state": "completed",
+        "original": {
+            "bpm": 120,
+            "key": "Cmaj",
+            "filename": "original.mp3",
+            "url": "https://storage.url/path/to/file.mp3"
+        },
+        # Function-specific data (e.g., "stem", "midi", "master", etc.)
+        "stem": {
+            "vocalsmp3": {
+                "bpm": 120,
+                "key": "Cmaj",
+                "filename": "vocals.mp3",
+                "url": "https://storage.url/path/to/vocals.mp3"
+            },
+            # Other stems...
+        },
+        # Other execution data...
+    },
+    # For some functions, function-specific data may be included here
+    "analysis": {
+        "bpm": 120,
+        "key": "Cmaj",
+        "execution_id": "execution-id"
+    },
+    "segmentation": {
+        # Segmentation data
+    },
+    "files": {
+        "folder": "./audial_results/execution-id_function-type",
+        "files": {
+            "filename1.mp3": "./audial_results/execution-id_function-type/filename1.mp3",
+            "filename2.mp3": "./audial_results/execution-id_function-type/filename2.mp3",
+            # Other downloaded files...
+        }
+    }
+}
+```
+
+The structure may vary slightly depending on the function, but will always include:
+1. `execution`: The raw API response data
+2. `files`: Information about the downloaded files
+   - `folder`: Path to the results folder
+   - `files`: Dictionary mapping filenames to local file paths
+
+Some functions may include additional fields with function-specific data, such as `analysis` for the `analyze` function.