idtap 0.1.5__tar.gz

idtap-0.1.5/CLAUDE.md

@@ -0,0 +1,110 @@
+# IDTAP Python API Development Guide
+
+## Overview
+The Python API (`idtap_api`) is a sophisticated client library for interacting with the IDTAP (Interactive Digital Transcription and Analysis Platform) server, specifically designed for transcribing, analyzing, and managing Hindustani music recordings.
+
+## Key Development Points
+
+### Dependencies Management
+- **Keep `Pipfile` and `pyproject.toml` in sync** - this is critical!
+- Add new packages: `pipenv install package-name`
+- Then manually add to `pyproject.toml` dependencies array
+- Core deps: requests, pyhumps, keyring, cryptography, PyJWT, pymongo, google-auth-oauthlib
+
+### Testing
+- **Unit tests**: `pytest python/idtap_api/tests/` (uses `responses` for HTTP mocking)
+- **Integration tests**: `python python/api_testing/api_test.py` (requires live server auth)
+- Test structure: Complete coverage of data models, client functionality, and authentication
+
+### Build/Package/Publish
+```bash
+python -m build
+python -m twine upload dist/*  # or --repository testpypi for testing
+```
+
+## Architecture
+
+### Main Components
+- **`SwaraClient`** (`client.py`) - Main HTTP client with OAuth authentication
+- **Data Models** (`/classes/`) - Rich musical transcription classes (Piece, Phrase, Trajectory, etc.)
+- **Authentication** (`auth.py` + `secure_storage.py`) - OAuth flow with secure token storage
+- **Utils** (`utils.py`) - camelCase ↔ snake_case conversion
+
+### Key Classes
+- **`Piece`**: Central transcription container with multi-track support, sections, audio association
+- **`SwaraClient`**: API interface with methods for transcription CRUD, audio download, permissions
+- **Musical Elements**: Phrase, Trajectory, Pitch, Raga, Section, Meter, Articulation
+
+### Security/Authentication
+- **OAuth Flow**: Server-based OAuth (not direct Google) → local HTTP server → secure storage
+- **Storage Layers**: OS Keyring (primary) → AES-256 encrypted file (fallback) → plaintext (legacy)
+- **CSRF Protection**: State parameter validation
+- **Permissions**: User-based access control with public/private visibility
+
+## Development Patterns
+
+### Code Conventions
+- **snake_case** for Python code
+- **camelCase ↔ snake_case** conversion via `pyhumps` for API communication
+- **Type hints** throughout
+- **Backwards compatibility** maintained (especially token storage migration)
+
+### Serialization Pattern
+```python
+class DataModel:
+    def to_json(self) -> Dict[str, Any]:
+        # Convert to dict with camelCase keys for API
+        
+    @staticmethod 
+    def from_json(obj: Dict[str, Any]) -> 'DataModel':
+        # Parse from API response with snake_case conversion
+```
+
+### Package Structure
+```
+python/idtap_api/
+├── __init__.py           # Public API exports
+├── client.py             # HTTP client (SwaraClient)
+├── auth.py               # OAuth authentication
+├── secure_storage.py     # Token security layers
+├── enums.py              # Instrument types, etc.
+├── utils.py              # camelCase conversion utilities
+├── classes/              # Musical data models
+└── tests/                # Unit tests
+```
+
+## API Endpoints (via SwaraClient)
+- **Transcriptions**: GET/POST `/api/transcription/{id}`, GET `/api/transcriptions`
+- **Data Export**: GET `/api/transcription/{id}/json`, `/api/transcription/{id}/excel`
+- **Audio**: GET `/audio/{format}/{id}.{format}`
+- **Permissions**: POST `/api/visibility`
+- **OAuth**: GET `/oauth/authorize`, POST `/oauth/token`
+
+## Musical Domain Knowledge
+- **Hindustani Music Focus**: Transcription system for Indian classical music
+- **Complex Data Models**: Supports microtonal pitches, ragas, articulations, meter cycles
+- **Multi-instrument**: Sitar, Vocal (Male/Female) with instrument-specific features
+- **Analytical Tools**: Trajectory categorization, phrase grouping, temporal analysis
+
+## Development Workflow
+1. **Data Model Development**: Create/modify classes in `/classes/` with proper serialization
+2. **Client Method Development**: Add HTTP methods in `client.py` with authentication
+3. **Testing**: Write unit tests (mocked) + integration tests (live API)  
+4. **Sync Dependencies**: Update both `Pipfile` and `pyproject.toml`
+5. **Build/Test/Publish**: Use standard Python packaging tools
+
+## Installation Commands
+```bash
+# Development
+pip install -e python/
+pipenv install --dev
+
+# Testing  
+pytest python/idtap_api/tests/
+python python/api_testing/api_test.py
+
+# Package management
+pipenv install package-name  # then manually add to pyproject.toml
+```
+
+This API provides a production-ready foundation for complex musical transcription analysis with modern security practices and comprehensive testing coverage.

idtap-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jon Myers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

idtap-0.1.5/MANIFEST.in

@@ -0,0 +1,11 @@
+# Include important files in source distribution
+include README.md
+include LICENSE
+include SECURITY.md
+include CLAUDE.md
+include requirements.txt
+recursive-include idtap *.py
+recursive-include idtap *.typed
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+exclude idtap.egg-info

idtap-0.1.5/PKG-INFO

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: idtap
+Version: 0.1.5
+Summary: Python client library for IDTAP - Interactive Digital Transcription and Analysis Platform for Hindustani music
+Author-email: Jon Myers <jon@swara.studio>
+Maintainer-email: Jon Myers <jon@swara.studio>
+License: MIT
+Project-URL: Homepage, https://swara.studio
+Project-URL: Documentation, https://github.com/UCSC-IDTAP/Python-API
+Project-URL: Repository, https://github.com/UCSC-IDTAP/Python-API
+Project-URL: Bug Tracker, https://github.com/UCSC-IDTAP/Python-API/issues
+Keywords: music,transcription,hindustani,indian-classical,musicology,ethnomusicology,raga,pitch-analysis,audio-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: requests-toolbelt>=1.0.0
+Requires-Dist: pyhumps>=3.8.0
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: PyJWT>=2.8.0
+Requires-Dist: google-auth-oauthlib>=1.0.0
+Requires-Dist: pymongo>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Provides-Extra: linux
+Requires-Dist: secretstorage>=3.3.0; extra == "linux"
+Dynamic: license-file
+
+# IDTAP Python API
+
+[![PyPI version](https://badge.fury.io/py/idtap-api.svg)](https://badge.fury.io/py/idtap-api)
+[![Documentation Status](https://readthedocs.org/projects/idtap-api/badge/?version=latest)](https://idtap-python-api.readthedocs.io/en/latest/?badge=latest)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Python client library for **IDTAP** (Interactive Digital Transcription and Analysis Platform) - a web-based research platform developed at UC Santa Cruz for transcribing, analyzing, and archiving Hindustani (North Indian classical) music recordings using trajectory-based notation designed specifically for oral melodic traditions.
+
+## About IDTAP
+
+IDTAP represents a paradigm shift in musical transcription and analysis. Rather than forcing oral traditions into Western notational frameworks, it uses **trajectories** as the fundamental musical unit—archetypal paths between pitches that capture the continuous melodic movement central to Hindustani music.
+
+**Key Innovation**: Instead of discrete notes, IDTAP models music through:
+- **Trajectory-based notation** - Continuous pitch contours rather than fixed notes
+- **Microtonal precision** - Cent-based tuning with flexible raga systems  
+- **Idiomatic articulations** - Performance techniques specific to each instrument
+- **Hierarchical segmentation** - Phrases, sections, and formal structures
+
+## Features
+
+- **Trajectory-Based Data Access** - Load and analyze transcriptions using the trajectory notation system
+- **Hindustani Music Analysis** - Work with raga-aware transcriptions and microtonal pitch data
+- **Audio Download** - Retrieve associated audio recordings in multiple formats
+- **Secure Authentication** - OAuth integration with encrypted token storage
+
+## Installation
+
+```bash
+pip install idtap-api
+```
+
+### Optional Dependencies
+
+For enhanced Linux keyring support:
+```bash
+pip install idtap-api[linux]
+```
+
+For development:
+```bash
+pip install idtap-api[dev]
+```
+
+## Quick Start
+
+### Authentication & Basic Usage
+
+```python
+from idtap_api import SwaraClient, Piece, Instrument
+
+# Initialize client - connects to swara.studio platform
+client = SwaraClient()  # Automatic OAuth via Google
+
+# Browse available transcriptions
+transcriptions = client.get_viewable_transcriptions()
+print(f"Found {len(transcriptions)} transcriptions")
+
+# Load a Hindustani music transcription
+piece_data = client.get_piece("transcription-id")
+piece = Piece.from_json(piece_data)
+
+print(f"Transcription: {piece.title}")
+print(f"Raga: {piece.raga.name if piece.raga else 'Unknown'}")
+print(f"Instrument: {piece.instrumentation}")
+print(f"Trajectories: {sum(len(p.trajectories) for p in piece.phrases)}")
+```
+
+### Working with Trajectory-Based Transcriptions
+
+```python
+# Analyze trajectory-based musical structure
+for phrase in piece.phrases:
+    print(f"Phrase {phrase.phrase_number}: {len(phrase.trajectories)} trajectories")
+    
+    # Examine individual trajectories (fundamental units of IDTAP)
+    for traj in phrase.trajectories:
+        if traj.pitch_array:
+            # Each trajectory contains continuous pitch movement
+            start_pitch = traj.pitch_array[0].pitch_number
+            end_pitch = traj.pitch_array[-1].pitch_number
+            print(f"  Trajectory {traj.traj_number}: {start_pitch:.2f} → {end_pitch:.2f}")
+            
+            # Check for articulations (performance techniques)
+            if traj.articulation:
+                techniques = [art.stroke for art in traj.articulation if art.stroke]
+                print(f"    Articulations: {', '.join(techniques)}")
+
+# Raga analysis (theoretical framework)
+if piece.raga:
+    print(f"Raga: {piece.raga.name}")
+    if hasattr(piece.raga, 'aroha') and piece.raga.aroha:
+        print(f"Aroha (ascending): {piece.raga.aroha}")
+    if hasattr(piece.raga, 'avaroha') and piece.raga.avaroha:  
+        print(f"Avaroha (descending): {piece.raga.avaroha}")
+```
+
+### Audio Handling
+
+```python
+# Download audio in different formats
+audio_bytes = client.download_audio("audio-id", format="wav")
+with open("recording.wav", "wb") as f:
+    f.write(audio_bytes)
+
+# Download all audio associated with a transcription
+client.download_and_save_transcription_audio(piece, directory="./audio/")
+```
+
+### Data Export
+
+```python
+# Export transcription data
+excel_data = client.excel_data(piece_id)
+with open("analysis.xlsx", "wb") as f:
+    f.write(excel_data)
+
+json_data = client.json_data(piece_id)
+with open("transcription.json", "wb") as f:
+    f.write(json_data)
+```
+
+### Working with Hindustani Music Data
+
+```python
+from idtap_api import Piece, Phrase, Trajectory, Pitch, Raga, Instrument
+
+# Example: Analyze a sitar transcription
+sitar_pieces = [t for t in transcriptions if t.get('instrumentation') == 'Sitar']
+
+for trans_meta in sitar_pieces[:3]:  # First 3 sitar pieces
+    piece = Piece.from_json(client.get_piece(trans_meta['_id']))
+    
+    # Count different types of trajectories (IDTAP's innovation)
+    trajectory_types = {}
+    for phrase in piece.phrases:
+        for traj in phrase.trajectories:
+            traj_type = getattr(traj, 'curve_type', 'straight')
+            trajectory_types[traj_type] = trajectory_types.get(traj_type, 0) + 1
+    
+    print(f"{piece.title}:")
+    print(f"  Raga: {piece.raga.name if piece.raga else 'Unknown'}")
+    print(f"  Trajectory types: {trajectory_types}")
+    
+    # Analyze articulation patterns (performance techniques)  
+    articulations = []
+    for phrase in piece.phrases:
+        for traj in phrase.trajectories:
+            if traj.articulation:
+                articulations.extend([art.stroke for art in traj.articulation])
+    
+    unique_arts = list(set(articulations))
+    print(f"  Articulations used: {', '.join(unique_arts[:5])}")  # First 5
+```
+
+## Key Classes
+
+### SwaraClient
+The main HTTP client for interacting with the IDTAP server.
+
+**Key Methods:**
+- `get_viewable_transcriptions()` - List accessible transcriptions
+- `get_piece(id)` - Load transcription data
+- `save_piece(data)` - Save transcription
+- `excel_data(id)` / `json_data(id)` - Export data
+- `download_audio(id, format)` - Download audio files
+- `get_waiver_text()` - Display the research waiver text that must be read
+- `agree_to_waiver(i_agree=True)` - Accept research waiver (required for first-time users)
+- `has_agreed_to_waiver()` - Check if waiver has been accepted
+
+### Musical Data Models
+
+- **`Piece`** - Central transcription container with metadata, audio association, and musical content
+- **`Phrase`** - Musical phrase containing trajectory data and categorizations
+- **`Trajectory`** - Detailed pitch movement data with timing and articulations
+- **`Pitch`** - Individual pitch points with frequency and timing information
+- **`Raga`** - Indian musical scale/mode definitions with theoretical rules
+- **`Section`** - Large structural divisions (alap, composition, etc.)
+- **`Meter`** - Rhythmic cycle and tempo information
+- **`Articulation`** - Performance technique annotations (meend, andolan, etc.)
+
+### Specialized Features
+
+- **Microtonal Pitch System** - Precise cent-based pitch representation
+- **Hindustani Music Theory** - Raga rules, sargam notation, gharana traditions
+- **Performance Analysis** - Ornament detection, phrase categorization
+- **Multi-Track Support** - Simultaneous transcription of melody and drone
+
+## Authentication
+
+The client uses OAuth 2.0 flow with Google authentication. On first use, it will:
+
+1. Open a browser for Google OAuth login
+2. Securely store the authentication token using:
+   - OS keyring (preferred)
+   - Encrypted local file (fallback)
+   - Plain text (legacy, discouraged)
+
+### Research Waiver Requirement
+
+**First-time users must agree to a research waiver** before accessing transcription data. If you haven't agreed yet, you'll see an error when trying to access transcriptions:
+
+```python
+client = SwaraClient()
+transcriptions = client.get_viewable_transcriptions()  # Will raise RuntimeError
+
+# First, read the waiver text
+waiver_text = client.get_waiver_text()
+print("Research Waiver:")
+print(waiver_text)
+
+# After reading, agree to the waiver
+client.agree_to_waiver(i_agree=True)
+transcriptions = client.get_viewable_transcriptions()  # Now works
+
+# Check waiver status
+if client.has_agreed_to_waiver():
+    print("Waiver agreed - full access available")
+```
+
+### Manual Token Management
+
+```python
+# Initialize without auto-login
+client = SwaraClient(auto_login=False)
+
+# Login manually when needed
+from idtap_api import login_google
+login_google()
+```
+
+## Advanced Usage
+
+### Batch Processing
+
+```python
+# Process multiple transcriptions
+transcriptions = client.get_viewable_transcriptions()
+
+for trans in transcriptions:
+    if trans.get('instrumentation') == 'Sitar':
+        piece = Piece.from_json(client.get_piece(trans['_id']))
+        
+        # Analyze sitar-specific features
+        total_meends = sum(
+            len([art for art in traj.articulation if art.stroke == 'meend'])
+            for phrase in piece.phrases
+            for traj in phrase.trajectories
+        )
+        print(f"{piece.title}: {total_meends} meends")
+```
+
+### Research Applications
+
+```python
+# Raga analysis across corpus
+raga_stats = {}
+for trans in transcriptions:
+    piece = Piece.from_json(client.get_piece(trans['_id']))
+    if piece.raga:
+        raga_name = piece.raga.name
+        raga_stats[raga_name] = raga_stats.get(raga_name, 0) + 1
+
+print("Raga distribution:", raga_stats)
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Unit tests
+pytest idtap_api/tests/
+
+# Integration tests (requires authentication)
+python api_testing/api_test.py
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## Documentation
+
+- **API Reference**: Full documentation of all classes and methods
+- **Musical Concepts**: Guide to Hindustani music terminology and theory
+- **Research Examples**: Academic use cases and analysis workflows
+
+## Platform Access
+
+- **IDTAP Web Platform**: [swara.studio](https://swara.studio)
+- **Source Code**: [github.com/jon-myers/idtap](https://github.com/jon-myers/idtap)
+- **Research Paper**: "Beyond Notation: A Digital Platform for Transcribing and Analyzing Oral Melodic Traditions" (ISMIR 2025)
+
+## Documentation
+
+📖 **Complete documentation is available at [idtap-python-api.readthedocs.io](https://idtap-python-api.readthedocs.io/)**
+
+- **[Installation Guide](https://idtap-python-api.readthedocs.io/en/latest/installation.html)** - Detailed setup instructions
+- **[Authentication](https://idtap-python-api.readthedocs.io/en/latest/authentication.html)** - OAuth setup and token management
+- **[Quickstart Tutorial](https://idtap-python-api.readthedocs.io/en/latest/quickstart.html)** - Get started in minutes
+- **[API Reference](https://idtap-python-api.readthedocs.io/en/latest/api/)** - Complete class and method documentation
+- **[Examples](https://idtap-python-api.readthedocs.io/en/latest/examples/)** - Real-world usage examples
+
+## Support
+
+- **GitHub Issues**: [Report bugs and request features](https://github.com/UCSC-IDTAP/Python-API/issues)
+- **Research Contact**: Jonathan Myers & Dard Neuman, UC Santa Cruz
+- **Platform**: [swara.studio](https://swara.studio)
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Citation
+
+If you use IDTAP in academic research, please cite the ISMIR 2025 paper:
+
+```bibtex
+@inproceedings{myers2025beyond,
+  title={Beyond Notation: A Digital Platform for Transcribing and Analyzing Oral Melodic Traditions},
+  author={Myers, Jonathan and Neuman, Dard},
+  booktitle={Proceedings of the 26th International Society for Music Information Retrieval Conference},
+  pages={},
+  year={2025},
+  address={Daejeon, South Korea},
+  url={https://swara.studio}
+}
+```
+
+---
+
+**IDTAP** was developed at UC Santa Cruz with support from the National Endowment for the Humanities. The platform challenges Western-centric approaches to music representation by creating tools designed specifically for oral melodic traditions, enabling scholars to study Hindustani music on its own terms while applying cutting-edge computational methodologies.