SwaraClient

The main client class for interacting with the IDTAP API.

class idtap.SwaraClient(base_url: str = 'https://swara.studio/', token_path: str | Path | None = None, auto_login: bool = True)[source]

Bases: object

Minimal client wrapping the public API served at https://swara.studio.

__init__(base_url: str = 'https://swara.studio/', token_path: str | Path | None = None, auto_login: bool = True) → None[source]

property user_id: str | None: Return the user ID if available, otherwise None.

load_token(token_path: str | Path | None = None) → None[source]: Load saved token and profile information from secure storage.

get_auth_info() → Dict[str, Any][source]

Get information about the current authentication and storage setup.

Returns:: Dict containing authentication status and storage information

get_piece(piece_id: str, fetch_rule_set: bool = True) → Any[source]

Return transcription JSON for the given id.

Parameters:

piece_id – The ID of the piece to fetch
fetch_rule_set – If True and raga has no ruleSet, fetch it from database

Returns:

Dictionary containing the piece data with ruleSet populated if needed

excel_data(piece_id: str) → bytes[source]: Export transcription data as Excel file.

json_data(piece_id: str) → bytes[source]: Export transcription data as JSON file.

save_piece(piece: Dict[str, Any]) → Any[source]: Save transcription using authenticated API route.

insert_new_transcription(piece: Dict[str, Any]) → Any[source]: Insert a new transcription document as the current authenticated user.

clone_transcription(piece_id: str, title: str | None = None, explicit_permissions: Dict[str, Any] | None = None, soloist: str | None = None, solo_instrument: str | None = None) → Any[source]

Clone a transcription, creating a new copy owned by the current user.

The server copies all transcription data (phrases, trajectories, pitches, raga, audio association, etc.) and assigns a new ID, owner, and timestamps.

Parameters:

piece_id – The ID of the transcription to clone.
title – Title for the cloned transcription. Defaults to server behavior.
explicit_permissions – Permission object with ‘edit’, ‘view’ (user ID lists) and ‘publicView’ (bool). Defaults to private.
soloist – Soloist name for the clone.
solo_instrument – Solo instrument for the clone.

Returns:

Server response with insertedId of the new transcription.

delete_transcription(piece_id: str) → Any[source]

Delete a transcription from the server.

Removes the transcription document and the reference from the user’s transcriptions array.

Parameters:: piece_id – The ID of the transcription to delete.
Returns:: Server response with deletedCount.

get_viewable_transcriptions(sort_key: str = 'title', sort_dir: str | int = 1, new_permissions: bool | None = None) → Any[source]: Return transcriptions viewable by the user.

update_visibility(artifact_type: str, _id: str, explicit_permissions: Dict[str, Any]) → Any[source]

has_agreed_to_waiver() → bool[source]

Check if the current user has agreed to the research waiver.

This makes a fresh API call to get the latest waiver status from the database.

Returns:: True if user has agreed to waiver, False otherwise

get_waiver_text() → str[source]

Get the research waiver text that users must agree to.

Returns:: The full waiver text

agree_to_waiver(i_agree: bool = False) → Any[source]

Agree to the research waiver after reading it.

You must first read the waiver text using get_waiver_text() and then explicitly set i_agree=True to confirm agreement.

Parameters:: i_agree – Must be True to confirm you have read and agree to the waiver
Returns:: Server response confirming waiver agreement
Raises:: RuntimeError – If not authenticated or if i_agree is not True

upload_audio(file_path: str, metadata: AudioMetadata, audio_event: 'AudioEventConfig' | None = None, progress_callback: Callable[[float], None] | None = None) → AudioUploadResult[source]

Upload audio recording with comprehensive metadata.

Requires the requests-toolbelt library for multipart encoding.

Parameters:

file_path – Path to the audio file to upload
metadata – AudioMetadata object with recording information. Ragas can be specified in multiple formats: - AudioRaga objects: AudioRaga(name=”Rageshree”) (recommended) - Strings: “Rageshree” (auto-converted to AudioRaga) - Name dicts: {“name”: “Rageshree”} (auto-converted to AudioRaga) - Legacy format: {“Rageshree”: {“performance_sections”: {}}} (auto-converted)
audio_event – Optional AudioEventConfig for associating with audio events
progress_callback – Optional callback for upload progress (0-100)

Returns:

AudioUploadResult with upload status and file information

Raises:

FileNotFoundError – If the audio file doesn’t exist
ValueError – If the file is not a supported audio format or metadata validation fails
RuntimeError – If upload fails

get_available_musicians() → List[Dict[str, Any]][source]: Get list of musicians in database.

get_available_ragas() → List[str][source]: Get list of ragas in database.

get_raga_rules(raga_name: str) → Dict[str, Any][source]

Get pitch rules for a specific raga.

Parameters:

raga_name – Name of the raga to get rules for

Returns:

Dictionary containing the raga’s pitch rules and updated date

Raises:

ValueError – If raga_name is empty or None
requests.HTTPError – If raga not found or API error

get_available_instruments(melody_only: bool = False) → List[str][source]: Get list of instruments in database.

get_location_hierarchy() → LocationHierarchy[source]: Get continent/country/city structure.

get_available_gharanas() → List[Dict[str, Any]][source]: Get list of gharanas in database.

get_performance_sections() → List[str][source]: Get list of performance sections.

get_event_types() → List[str][source]: Get list of audio event types.

get_editable_audio_events() → List[Dict[str, Any]][source]: Get audio events the user can edit.

validate_metadata(metadata: AudioMetadata) → ValidationResult[source]: Validate metadata against platform requirements.

logout(confirm: bool = False) → bool[source]

Log out the current user and clear all stored authentication tokens.

This will: - Clear tokens from OS keyring, encrypted storage, and plaintext files - Reset the client’s authentication state - Require re-authentication for future API calls

Parameters:: confirm – Set to True to confirm logout without interactive prompt
Returns:: True if logout was successful, False otherwise

download_audio(audio_id: str, format: str = 'wav') → bytes[source]

Download audio recording by audio ID.

Parameters:

audio_id – The audio recording ID
format – Audio format (wav, mp3, opus)

Returns:

Raw audio data as bytes

download_transcription_audio(piece: Dict[str, Any] | Piece, format: str = 'wav') → bytes | None[source]

Download audio recording associated with a transcription.

Parameters:

piece – Transcription piece data (dict or Piece object)
format – Audio format (wav, mp3, opus)

Returns:

Raw audio data as bytes, or None if no audio is associated

save_audio_file(audio_data: bytes, filename: str, filepath: str | None = None) → str[source]

Save audio data to a file.

Parameters:

audio_data – Raw audio data from download_audio()
filename – Output filename (should include extension)
filepath – Directory to save file (defaults to user’s Downloads folder)

Returns:

Full path to the saved file

download_and_save_transcription_audio(piece: Dict[str, Any] | Piece, format: str = 'wav', filepath: str | None = None, filename: str | None = None) → str | None[source]

Download and save audio recording associated with a transcription.

Parameters:

piece – Transcription piece data (dict or Piece object)
format – Audio format (wav, mp3, opus)
filepath – Directory to save file (defaults to Downloads folder)
filename – Custom filename (defaults to transcription title + ID)

Returns:

Full path to saved file, or None if no audio is associated

download_spectrogram_data(audio_id: str) → bytes[source]

Download gzip-compressed spectrogram data.

Parameters:: audio_id – The audio recording ID
Returns:: Gzipped binary data containing uint8 spectrogram array

download_spectrogram_metadata(audio_id: str) → Dict[str, Any][source]

Download spectrogram shape metadata.

Parameters:: audio_id – The audio recording ID
Returns:: [freq_bins, time_frames]
Return type:: Dictionary with ‘shape’ key

get_audio_recording(audio_id: str) → Dict[str, Any][source]

Get audio recording metadata by ID.

Fetches complete recording metadata including duration, musicians, ragas, location, and permissions.

Parameters:

audio_id – The audio recording ID

Returns:

duration: Audio duration in seconds (float)
musicians: Dictionary of performer information
raags: Dictionary of raga information
title: Recording title
etc.

Return type:

Dictionary with recording metadata including

Raises:

requests.HTTPError – If recording not found (404)

save_transcription(piece: Piece, fill_duration: bool = True) → Any[source]

Save a transcription piece to the server.

Handles both new transcriptions (without _id) and existing transcriptions (with _id).

Parameters:

piece – The Piece object or dict to save
fill_duration – Whether to automatically fill remaining duration with silence

Returns:

Server response from the save operation

single_query(transcription_id: str, segmentation: SegmentationType | str = SegmentationType.PHRASE, designator: DesignatorType | str = DesignatorType.INCLUDES, category: CategoryType | str = CategoryType.TRAJECTORY_ID, pitch: Pitch | None = None, sequence_length: int | None = None, trajectory_id: int | None = None, vowel: str | None = None, consonant: str | None = None, instrument_idx: int = 0, **kwargs) → Query[source]

Create and execute a single query on a transcription.

Parameters:

transcription_id – ID of the transcription to query
segmentation – Type of segmentation (phrase, group, etc.)
designator – Query designator (includes, excludes, etc.)
category – Query category (trajectoryID, pitch, etc.)
pitch – Pitch object to search for (if category is pitch)
sequence_length – Length of trajectory sequences (if needed)
trajectory_id – Trajectory ID to search for (if category is trajectoryID)
vowel – Vowel to search for (if category is vowel)
consonant – Consonant to search for (if category is consonant)
instrument_idx – Index of instrument track to query
**kwargs – Additional query parameters

Returns:

Query object with results

multiple_query(queries: List[QueryType | Dict[str, Any]], transcription_id: str, segmentation: SegmentationType | str = SegmentationType.PHRASE, sequence_length: int | None = None, min_dur: float = 0.0, max_dur: float = 60.0, every: bool = True, instrument_idx: int = 0) → tuple[List[List[Trajectory]], List[int | str | Dict[str, int]], List[QueryAnswerType]][source]

Execute multiple queries on a transcription and combine results.

Parameters:

queries – List of query specifications
transcription_id – ID of transcription to query
segmentation – Segmentation type for all queries
sequence_length – Sequence length for trajectory sequences
min_dur – Minimum duration filter
max_dur – Maximum duration filter
every – If True, require all queries to match; if False, any query can match
instrument_idx – Index of instrument track to query

Returns:

Tuple of (trajectories, identifiers, query_answers)

Usage Examples

Basic Usage

from idtap import SwaraClient

client = SwaraClient()
transcriptions = client.get_transcriptions()

Custom Configuration

# Use custom server (for development)
client = SwaraClient(base_url="http://localhost:3000")

Methods Overview

Transcription Methods

SwaraClient.delete_transcription(piece_id)

Delete a transcription from the server.

Audio Methods

`SwaraClient.upload_audio`(file_path, metadata)	Upload audio recording with comprehensive metadata.
`SwaraClient.download_audio`(audio_id[, format])	Download audio recording by audio ID.

Export Methods

Permission Methods

SwaraClient.update_visibility(artifact_type, ...)