Merge pull request #2 from ofspectrum/sync-sdk-v1.1.4

Sync SDK v1.1.4 from neo

Author: jlw463195395

.github/workflows/publish.yml

@@ -2,6 +2,7 @@
 name: Publish to PyPI
 
 on:
+  workflow_dispatch:
   release:
     types: [published]
   push:

.github/workflows/tag-release.yml

@@ -0,0 +1,58 @@
+# Create a release tag after SDK changes land on main.
+name: Tag SDK Release
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'pyproject.toml'
+  workflow_dispatch:
+
+permissions:
+  actions: write
+  contents: write
+
+jobs:
+  tag-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Read SDK version
+        id: version
+        run: |
+          VERSION=$(python - <<'PY'
+          import tomllib
+
+          with open("pyproject.toml", "rb") as f:
+              print(tomllib.load(f)["project"]["version"])
+          PY
+          )
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Create release tag and dispatch publish
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          TAG="v$VERSION"
+
+          git fetch --tags
+          if git rev-parse "refs/tags/$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists, skipping"
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+
+          # Tags pushed with GITHUB_TOKEN do not trigger push workflows, so
+          # dispatch the existing publish workflow explicitly at the new tag.
+          gh workflow run publish.yml --ref "$TAG"

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.1.4
+
+- Updated token documentation for Standard, Pro, and eligible Enterprise workflows.
+- Clarified the recommended encode save workflow using `result.save()`.
+- Clarified quota and notebook documentation with account-level wording.
+- Removed default verification-key examples and internal implementation wording from public docs.
+
+## 1.1.3
+
+- Previous public SDK release.

README.md

@@ -1,6 +1,6 @@
 # OfSpectrum Python SDK
 
-Official Python SDK for the OfSpectrum Audio Watermarking API.
+Official Python SDK for the OfSpectrum audio watermarking API.
 
 ## Installation
 
@@ -19,122 +19,154 @@ pip install -e /path/to/neo/sdk
 ```python
 from ofspectrum import OfSpectrum
 
-# Initialize client with your API key
 client = OfSpectrum(api_key="your_api_key")
 
-# Create a watermark token (simple - uses "standard" type by default)
+# Create a Standard token.
 token = client.tokens.create(name="Production Token")
 print(f"Created token: {token.id}")
 
-# Or specify a type (creator/enterprise require public_key)
-# token = client.tokens.create(
-#     name="Creator Token",
-#     token_type="creator",
-#     public_key=12345
-# )
-
-# Encode watermark into audio
+# Encode and save watermarked audio.
 result = client.audio.encode(
     audio="input.mp3",
     token_id=token.id,
-    output_path="watermarked.mp3"
 )
+result.save("watermarked.mp3")
 print(f"Encoded {result.audio_duration}s of audio")
 
-# Decode (detect) watermark from audio
+# Decode watermark from audio.
 decode = client.audio.decode("suspect.mp3")
 if decode.watermarked:
-    print(f"Watermark detected! Token ID: {decode.token_id}")
+    print(f"Watermark detected. Token ID: {decode.token_id}")
 else:
     print("No watermark detected")
 
-# Check your quota
+# Check your quota.
 quota = client.quotas.get_encode_quota()
 print(f"Remaining encode quota: {quota.remaining}/{quota.quota_limit} seconds")
 ```
 
-## Features
+## Token Management
 
-### Token Management
+Standard tokens are the simplest option. Pro tokens support workflow-specific verification-key configuration. Enterprise token configuration is available for eligible enterprise accounts or existing enterprise tokens.
 
 ```python
-# List all tokens
+import os
+
+# List all tokens.
 tokens = client.tokens.list()
 
-# Get a specific token
+# Get a specific token.
 token = client.tokens.get("token-uuid")
 
-# Update a token
+# Create a Pro token when your workflow requires a configurable verification key.
+verification_key = int(os.environ["OFSPECTRUM_PUBLIC_KEY"])
+token = client.tokens.create(
+    name="Pro Token",
+    token_type="pro",
+    public_key=verification_key,
+)
+
+# Update a token name.
 token = client.tokens.update(
     token_id="token-uuid",
-    name="New Name"
+    name="New Name",
 )
 
-# Note: Token deletion is not available via API.
-# Tokens are consumable resources.
+# Update a Pro or eligible Enterprise token verification key.
+token = client.tokens.update(
+    token_id="token-uuid",
+    public_key=verification_key,
+)
 ```
 
-### Audio Watermarking
+Token deletion is not available via API. Tokens are consumable resources.
+
+## Audio Watermarking
 
 ```python
-# Encode with custom settings
 result = client.audio.encode(
     audio="input.mp3",
     token_id=token.id,
-    strength=1.0,          # 0.1-2.0
-    normalize=True,         # Smooth audio to reduce artifacts
-    check_watermark=True,   # Check for existing watermark first
-    output_path="output.mp3"
+    strength=1.0,
+    smooth=True,
 )
+result.save("output.mp3")
 
-# Decode watermark from audio file
 decode = client.audio.decode("suspect.mp3")
 if decode.watermarked:
     print(f"Token: {decode.token_id}")
 ```
 
-### Notebook (Notes) Management
+Use `decode(..., public_key=verification_key)` only when your workflow requires an explicit verification key.
+
+## Streaming PCM Encode
+
+Use `stream_encode_pcm()` when your application already works with raw PCM audio or needs low-latency streaming from a file-processing pipeline, microphone, call, meeting, or live stream.
+
+The input must be raw PCM float32 little-endian bytes. 48 kHz mono is recommended. The SDK does not currently decode MP3/WAV/FLAC files, resample audio, or convert containers for this streaming method.
+
+```python
+def chunk_pcm(pcm_bytes: bytes, chunk_seconds: float = 0.5):
+    sample_rate = 48000
+    channels = 1
+    bytes_per_second = sample_rate * channels * 4
+    chunk_size = int(bytes_per_second * chunk_seconds)
+    for offset in range(0, len(pcm_bytes), chunk_size):
+        yield pcm_bytes[offset:offset + chunk_size]
+
+result = client.audio.stream_encode_pcm(
+    pcm_chunks=chunk_pcm(pcm_f32le_bytes),
+    token_id=token.id,
+    sample_rate=48000,
+    channels=1,
+    smooth=True,
+)
+
+encoded_pcm = result.encoded_pcm
+print(f"Encoded {result.audio_duration:.2f}s of PCM")
+```
+
+`encoded_pcm` is raw PCM float32 little-endian, not WAV or MP3. Wrap it in a WAV container or encode it to your desired output format before playback or download.
+
+## Notebook Management
+
+Attach notes and media files to tokens. Private notebooks require a credential, and limits depend on your account and token configuration.
 
 ```python
-# Create a public notebook for a token
 notebook = client.notebooks.create(
     token_id=token.id,
     note_name="Release Notes",
-    text_content="## Version 1.0\n\nInitial release.",
-    is_public=True
+    text_content="## Version 1.0\n\nRelease notes.",
+    is_public=True,
 )
 
-# Create a private notebook (default password: "123")
-private_nb = client.notebooks.create(
+private_notebook = client.notebooks.create(
     token_id=token.id,
     note_name="Private Notes",
     text_content="Confidential content",
     is_public=False,
-    credential_val="123"  # Optional, defaults to "123"
+    credential_val="choose-a-secure-credential",
 )
 
-# Upload media to notebook
 client.notebooks.upload_media(
     note_id=notebook.id,
-    file="cover.jpg"
+    file="cover.jpg",
 )
 
-# List notebooks for a token
 notebooks = client.notebooks.list(token_id=token.id)
 ```
 
-### Quota Checking
+## Quota Checking
 
 ```python
-# Get all quotas
-quotas = client.quotas.get_all()
-for quota in quotas:
-    print(f"{quota.service_name}: {quota.remaining}/{quota.quota_limit}")
+quota = client.quotas.get_encode_quota()
+print(f"Remaining encode quota: {quota.remaining}")
+
+decode_quota = client.quotas.get_decode_quota()
+print(f"Remaining decode quota: {decode_quota.remaining}")
 
-# Check if encoding is available
 if client.quotas.check_encode_available(duration_seconds=300):
-    # Proceed with encoding
-    pass
+    result = client.audio.encode(audio="input.mp3", token_id=token.id)
 ```
 
 ## Error Handling
@@ -152,60 +184,20 @@ from ofspectrum import (
 try:
     result = client.audio.encode(audio="input.mp3", token_id="...")
 except RateLimitError as e:
-    print(f"Rate limited! Retry after {e.retry_after} seconds")
+    print(f"Rate limited. Retry after {e.retry_after} seconds")
 except QuotaExceededError as e:
     print(f"Quota exceeded for {e.service}")
 except WatermarkExistsError:
-    print("Audio already has a watermark!")
+    print("Audio already has a watermark")
 except AuthenticationError:
     print("Invalid API key")
 except OfSpectrumError as e:
     print(f"API error: {e.code} - {e.message}")
 ```
 
-## Retry Logic
-
-```python
-from ofspectrum import OfSpectrum, RetryConfig, with_retry
-
-# Use built-in retry decorator
-@with_retry(RetryConfig(max_retries=3))
-def encode_with_retry():
-    return client.audio.encode(...)
-
-# Or configure retry globally
-config = RetryConfig(
-    max_retries=5,
-    initial_delay=1.0,
-    max_delay=60.0,
-    exponential_base=2.0,
-    jitter=True
-)
-```
-
 ## Context Manager
 
 ```python
-# Recommended: Use context manager for automatic cleanup
 with OfSpectrum(api_key="your_api_key") as client:
     tokens = client.tokens.list()
 ```
-
-## Configuration
-
-```python
-client = OfSpectrum(
-    api_key="your_api_key",
-    base_url="https://api.ofspectrum.com/api/v1",  # Optional: custom base URL
-    timeout=120.0  # Optional: request timeout in seconds
-)
-```
-
-## Requirements
-
-- Python 3.8+
-- httpx >= 0.24.0
-
-## License
-
-MIT License

ofspectrum/__init__.py

@@ -1,15 +1,15 @@
 """
 OfSpectrum Python SDK
 
-Audio watermarking and AI detection API client.
+Audio watermarking API client.
 
 Example:
     from ofspectrum import OfSpectrum
 
     client = OfSpectrum(api_key="your_api_key")
 
     # Create a token
-    token = client.tokens.create(name="My Token", token_type="creator")
+    token = client.tokens.create(name="My Token", token_type="pro")
 
     # Encode watermark
     result = client.audio.encode(
@@ -29,7 +29,7 @@
     print(f"Remaining: {quota.remaining}/{quota.quota_limit}")
 """
 
-__version__ = "1.1.3"
+__version__ = "1.1.4"
 __author__ = "OfSpectrum"
 
 from .client import OfSpectrum, AsyncOfSpectrum
@@ -54,6 +54,7 @@
     NotebookCreateParams,
     EncodeResult,
     DecodeResult,
+    StreamingEncodeResult,
     Quota,
     QuotaList,
 )
@@ -83,6 +84,7 @@
     "NotebookCreateParams",
     "EncodeResult",
     "DecodeResult",
+    "StreamingEncodeResult",
     "Quota",
     "QuotaList",
     # Utils