feat: add comprehensive spectrogram data access and visualization support

Resolves Issue #46

Add complete spectrogram support to enable programmatic access to the same
high-quality constant-Q spectrograms used in the IDTAP web application, with
extensive matplotlib integration for computational musicology research.

## New Features:

### SpectrogramData Class (`idtap/spectrogram.py`)
- **Data Loading**:
  - `from_audio_id(audio_id, client)` - Download from server
  - `from_piece(piece, client)` - Load from Piece object
  - Auto-decompresses gzipped spectrogram data from swara.studio

- **Transformations**:
  - `apply_intensity(power)` - Power-law contrast enhancement (1.0-5.0)
  - `apply_colormap(data, cmap)` - 35+ matplotlib colormaps
  - `crop_frequency(min_hz, max_hz)` - Frequency range cropping
  - `crop_time(start_time, end_time)` - Time range cropping

- **Matplotlib Integration** (for research workflows):
  - `plot_on_axis(ax, ...)` - Plot on existing axis for overlays
  - `get_plot_data(power, apply_cmap, cmap)` - Get processed data + extent
  - `get_extent()` - Get matplotlib extent [left, right, bottom, top]

- **Image Generation**:
  - `to_image(width, height, power, cmap)` - Generate PIL Image
  - `to_matplotlib(figsize, power, cmap)` - Generate standalone figure
  - `save(filepath, ...)` - Save to file (PNG, JPG, etc.)

- **Properties**:
  - `shape`, `duration`, `time_resolution`, `freq_bins`

### SwaraClient Updates (`idtap/client.py`)
- `download_spectrogram_data(audio_id)` - Download compressed data
- `download_spectrogram_metadata(audio_id)` - Download shape metadata

### Dependencies (`pyproject.toml`, `Pipfile`)
- Added `numpy>=1.20.0` for array processing
- Added `pillow>=9.0.0` for image generation
- Added `matplotlib>=3.5.0` for visualization

## Testing:
- 36 comprehensive test cases covering:
  - Data loading and initialization
  - Intensity transforms and colormap application
  - Frequency and time cropping
  - Matplotlib integration methods
  - Image generation and saving
  - All properties and edge cases
- **All 401 tests pass** (365 existing + 36 new)

## Usage Example:

```python
from idtap import SpectrogramData, get_piece
import matplotlib.pyplot as plt

# Load spectrogram
piece = get_piece("transcription_id")
spec = SpectrogramData.from_piece(piece)

# Create visualization with spectrogram underlay
fig, ax = plt.subplots(figsize=(12, 6))
spec.plot_on_axis(ax, power=2.5, cmap='viridis', alpha=0.6, zorder=0)

# Overlay pitch contour
ax.plot(times, freqs, 'r-', linewidth=2, zorder=1)
ax.set_xlabel('Time (s)')
ax.set_ylabel('Frequency (Hz)')

plt.savefig('figure.png', dpi=300)
```

## Documentation Updates:
- Updated CLAUDE.md with testing warning about browser authorization

## Design Decisions:
- Follows librosa/matplotlib patterns for research workflows
- Optional client parameter (creates if not provided)
- No caching in MVP (users can cache manually)
- Uses matplotlib colormaps (close enough to D3, simpler)
- Loads entire spectrogram into memory (suitable for typical sizes)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jon-myers

CLAUDE.md

@@ -16,6 +16,11 @@ The Python API (`idtap`) is a sophisticated client library for interacting with
 - **Integration tests**: `python python/api_testing/api_test.py` (requires live server auth)
 - Test structure: Complete coverage of data models, client functionality, and authentication
 
+**⚠️ IMPORTANT FOR CLAUDE: Before running the full test suite (`pytest idtap/tests/`), ALWAYS warn Jon first!**
+- Some tests may require browser authorization for OAuth authentication
+- Running tests without warning can waste time waiting for authorization that Jon doesn't realize is needed
+- Best practice: Ask "Ready to run the full test suite? (May require browser authorization)" before executing
+
 ### Build/Package/Publish - AUTOMATED via GitHub Actions
 **⚠️ IMPORTANT: Manual publishing is now automated. See "Automated Version Management" section below.**
 

Pipfile

@@ -14,7 +14,10 @@ build = "*"
 twine = "*"
 requests-toolbelt = "*"
 pyhumps = "*"
-idtap = "*"
+idtap = "==0.1.34"
+numpy = "*"
+pillow = "*"
+matplotlib = "*"
 
 [dev-packages]
 responses = "*"

Pipfile.lock

@@ -21,6 +21,7 @@
 from .classes.trajectory import Trajectory
 
 from .enums import Instrument
+from .spectrogram import SpectrogramData, SUPPORTED_COLORMAPS
 from .audio_models import (
     AudioMetadata,
     AudioUploadResult,
@@ -74,6 +75,9 @@
     "Trajectory",
     "Instrument",
     "login_google",
+    # Spectrogram
+    "SpectrogramData",
+    "SUPPORTED_COLORMAPS",
     # Audio upload classes
     "AudioMetadata",
     "AudioUploadResult", 

idtap/__init__.py

@@ -684,6 +684,30 @@ def download_and_save_transcription_audio(self, piece: Union[Dict[str, Any], Pie
         # Save file and return path
         return self.save_audio_file(audio_data, filename, filepath)
 
+    def download_spectrogram_data(self, audio_id: str) -> bytes:
+        """Download gzip-compressed spectrogram data.
+
+        Args:
+            audio_id: The audio recording ID
+
+        Returns:
+            Gzipped binary data containing uint8 spectrogram array
+        """
+        endpoint = f"spec_data/{audio_id}/spec_data.gz"
+        return self._get(endpoint)
+
+    def download_spectrogram_metadata(self, audio_id: str) -> Dict[str, Any]:
+        """Download spectrogram shape metadata.
+
+        Args:
+            audio_id: The audio recording ID
+
+        Returns:
+            Dictionary with 'shape' key: [freq_bins, time_frames]
+        """
+        endpoint = f"spec_data/{audio_id}/spec_shape.json"
+        return self._get(endpoint)
+
     def save_transcription(self, piece: Piece, fill_duration: bool = True) -> Any:
         """Save a transcription piece to the server.