transcodely 0.3.7__tar.gz → 0.3.9__tar.gz

{transcodely-0.3.7 → transcodely-0.3.9}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.5
 Name: transcodely
-Version: 0.3.7
-Summary: Official Python SDK for the Transcodely video transcoding API
-Project-URL: Homepage, https://transcodely.com
-Project-URL: Documentation, https://transcodely.com/docs
+Version: 0.3.9
+Summary: Official Python SDK for Transcodely — encode video to HLS, DASH and MP4 into your own S3, GCS or R2 bucket, with DRM and signed playback.
+Project-URL: Homepage, https://www.transcodely.com
+Project-URL: Documentation, https://www.transcodely.com/docs
 Project-URL: Repository, https://github.com/transcodely/transcodely-python
 Project-URL: Issues, https://github.com/transcodely/transcodely-python/issues
 Author: Transcodely
 License-Expression: MIT
 License-File: LICENSE
-Keywords: connect-rpc,dash,encoding,hls,streaming,transcodely,transcoding,video
+Keywords: abr,cmaf,connect-rpc,dash,drm,encoding,fairplay,ffmpeg,hls,r2,s3,signed-urls,streaming,transcodely,transcoding,video,video-hosting,widevine
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -37,7 +37,9 @@ Description-Content-Type: text/markdown
 
 # transcodely
 
-Official Python SDK for the [Transcodely](https://transcodely.com) video transcoding API.
+Official Python SDK for [Transcodely](https://www.transcodely.com) — encode video into
+HLS, DASH and MP4 and write it to your own S3, GCS or R2 bucket, with DRM, signed
+playback and deterministic output paths. Or let Transcodely host and deliver it.
 
 ```bash
 pip install transcodely
@@ -75,6 +77,49 @@ with Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"]) as client:
 
 The simplified-string form (`"hls"`, `"h264"`, `"1080p"`) is what the API actually emits over the wire — the SDK round-trips it transparently to and from the proto enum integers.
 
+## Read the output report
+
+Every completed output carries a report of what the produced file actually
+turned out to be — measured from the encoded file rather than copied from the
+request — plus the verdict of comparing those measurements against what was
+asked for.
+
+```python
+from transcodely.types import OutputReport
+
+done = client.jobs.get(job.id)
+
+for output in done.outputs:
+    if not output.HasField("report"):
+        continue  # not measured — never "nothing wrong"
+
+    report: OutputReport = output.report
+    print(
+        output.id,
+        report.video.codec,
+        f"{report.video.width}x{report.video.height}",
+        f"{report.duration_seconds}s",
+    )
+
+    if not report.verdict.matches_request:
+        for m in report.verdict.mismatches:
+            print(f"  {m.field}: asked for {m.expected}, got {m.actual}")
+```
+
+Check `output.HasField("report")` rather than truthiness: an absent report means
+"not measured", which is not the same as a report that found nothing wrong.
+Branch on `m.field` — it comes from a fixed vocabulary (`video.codec`,
+`video.resolution`, `duration_seconds`, …) — rather than on the values beside
+it. For an ABR ladder the facts describe the highest-resolution rendition, the
+same one the verdict judges; per-rendition detail stays in `variant_results`.
+
+An output encoded with per-title content-aware analysis also carries
+`report.content_aware`: the VMAF target the search aimed at, the score it reached
+on its samples, and the CRF it chose. It describes the SEARCH, not the delivered
+file — `vmaf_achieved` scores short samples taken before the real encode, which
+is never scored itself. Check `report.HasField("content_aware")`; an ordinary
+output has none.
+
 ## AI captions
 
 Add auto-generated captions to any output with a `generate` subtitle track. Leave `language` empty (or set `"auto"`) to auto-detect the spoken language, or pass an ISO 639-2 code to force one. A per-job fee is metered by source minute and surfaced on `job.fees`; produced captions appear on `job.subtitle_results` with `auto_generated=True`.
@@ -119,9 +164,13 @@ client.jobs            # create / get / list / cancel / confirm / watch
 client.videos          # upload helpers, multipart, create_from_url, get / list / update / delete / watch, get_stats / list_top_videos
 client.presets         # create / get / get_by_slug / list / update / duplicate / archive
 client.origins         # create / get / list / update / validate / archive
+client.ingest_rules    # create / get / list / update / delete / list_events / test / replay_event
 client.apps            # create / get / list / update / archive / enable_hosting
 client.api_keys        # create / get / list / revoke
 client.organizations   # create / get / list / update / check_slug
+client.billing         # list_invoices / retrieve / retrieve_upcoming / retrieve_profile / create_portal_session
+                       #   + retrieve_budget / set_budget / clear_budget
+                       #   + retrieve_outstanding_balance / settle_outstanding_balance
 client.memberships     # list / get / update_role / remove
 client.users           # get_me / get / list / update_me
 client.health          # check
@@ -266,6 +315,120 @@ r2 = {
 
 Provide either `account_id` or `endpoint`, never both. `jurisdiction` only applies when `account_id` is set.
 
+## Ingest rules
+
+An ingest rule is a standing instruction on one readable origin: *when an object
+matching these filters lands, create this job for it*. Your storage provider
+posts its object-created events to the rule's endpoint, and no server of yours
+is in the path. Amazon S3 via SNS, Google Cloud Storage via a Pub/Sub push
+subscription, Supabase Storage via a database webhook, and a generic shape for
+anything else are all recognised from the payload.
+
+```python
+created = client.ingest_rules.create(
+    origin_id="ori_a1b2c3d4e5f6",
+    name="Watch uploads/",
+    filters={
+        "prefix": "uploads/",
+        "suffixes": [".mp4", ".mov"],
+        "min_bytes": 1024,  # ignore the zero-byte placeholder some clients write first
+    },
+    action={
+        "outputs": [{"preset": "web_1080p_standard"}],
+        "managed": True,  # host and deliver the result; use output_origin_id for your own bucket
+        "priority": "standard",
+    },
+)
+
+print("point your bucket notifications at", created.rule.endpoint_url)
+print("secret (shown once):", created.secret)
+```
+
+`created.secret` is the **only** time the inbound secret is readable — store it
+wherever the event sender will read it from. A later `get` returns just
+`secret_prefix` and `secret_hint`. Lost it? `update` with `rotate_secret=True`
+issues a new one, and the previous one keeps working for 24 hours so the sender
+can be changed without dropping an event.
+
+Every delivery is recorded, whether or not it became a job:
+
+```python
+for event in client.ingest_rules.list_events(rule_id=created.rule.id).auto_paging_iter():
+    print(event.id, event.object_key, event.status, event.reason)
+```
+
+A `skipped` event names why in `reason` — `filter_prefix`, `filter_suffix`,
+`filter_content_type`, `filter_size`, `bucket_mismatch`, `rule_disabled`, or
+`duplicate`. A `failed` one carries the API error code that refused the job,
+such as `limit_exceeded`. Narrow the log to either with the simplified status
+string: `list_events(status="skipped")`.
+
+Deduplication is permanent: an object is identified by (rule, bucket, key,
+etag), so re-sending the event or re-uploading the same bytes produces nothing.
+To give an object another pass — one that arrived while the rule was paused, or
+was refused while the account was over its cap — replay it:
+
+```python
+replayed = client.ingest_rules.replay_event("sev_a1b2c3d4e5f6g7")
+print(replayed.id, "is back in", StorageEventStatus.Name(replayed.status))
+```
+
+Only `skipped` and `failed` events can be replayed. When an `update` switches a
+paused rule back on, the response reports how large that backlog is in
+`events_skipped_while_disabled`.
+
+Before wiring the provider up, dry-run a key against the rule with
+`client.ingest_rules.test(...)`: it reports whether the filters match and, when
+they do, the exact job request the rule would submit. Nothing is stored.
+
+## Billing
+
+Billing settles a whole organization, so `client.billing` needs a dashboard session token for an
+organization **owner** plus the organization it is for — an API key is scoped to one app and is
+rejected outright:
+
+```python
+client = Transcodely("tk_session_token", organization_id="org_f6g7h8i9j0")
+
+client.billing.retrieve_upcoming()  # what the current period has accrued
+client.billing.list_invoices(limit=12)
+```
+
+Three numbers live here and they are not interchangeable:
+
+| Call | What it answers | Enforces? |
+|---|---|---|
+| `billing.retrieve_upcoming()` | What the **current period** has accrued | No |
+| `billing.retrieve_budget()` | Spend against the org's own monthly budget | No — emails only |
+| `billing.retrieve_outstanding_balance()` | What is **unsettled**, incl. earlier periods | Yes, at the hard stop |
+| `apps.set_spend_limit(app_id, eur)` | One app's monthly cap | Yes, at 100% |
+
+Budgets notify; limits block:
+
+```python
+client.billing.set_budget(500.0)  # emails at 50% / 80% / 100%, restricts nothing
+client.billing.clear_budget()  # turns the alerts off
+```
+
+The outstanding balance is the platform's own exposure control. Reminder emails go out at 80%,
+100%, 125%, 150% and 175% of `threshold_cents` and restrict nothing; only at `hard_stop_cents`
+(twice the threshold) are **new** jobs refused with code `outstanding_balance_exceeded` — queued
+and running work still finishes and videos keep playing. Paying lifts the block on the next
+request:
+
+```python
+balance = client.billing.retrieve_outstanding_balance()
+if balance.blocked and balance.settlement_available:
+    result = client.billing.settle_outstanding_balance()
+    print(result.settlement.invoice_id, result.balance.outstanding_cents)  # → 0
+```
+
+Check `settlement_available` before offering a "pay now" action: settlement raises
+`PreconditionError` with code `settlement_unavailable` where the rail is switched off, and
+`nothing_outstanding` when there is nothing to pay. Job creates refused for money reasons carry
+`billing_past_due` (a statement is unpaid) or `outstanding_balance_exceeded` (too much unbilled
+usage) — neither clears by retrying, so back-off is the wrong response to both.
+
 ## Errors
 
 All exceptions inherit from `TranscodelyError`:

{transcodely-0.3.7 → transcodely-0.3.9}/README.md

@@ -1,6 +1,8 @@
 # transcodely
 
-Official Python SDK for the [Transcodely](https://transcodely.com) video transcoding API.
+Official Python SDK for [Transcodely](https://www.transcodely.com) — encode video into
+HLS, DASH and MP4 and write it to your own S3, GCS or R2 bucket, with DRM, signed
+playback and deterministic output paths. Or let Transcodely host and deliver it.
 
 ```bash
 pip install transcodely
@@ -38,6 +40,49 @@ with Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"]) as client:
 
 The simplified-string form (`"hls"`, `"h264"`, `"1080p"`) is what the API actually emits over the wire — the SDK round-trips it transparently to and from the proto enum integers.
 
+## Read the output report
+
+Every completed output carries a report of what the produced file actually
+turned out to be — measured from the encoded file rather than copied from the
+request — plus the verdict of comparing those measurements against what was
+asked for.
+
+```python
+from transcodely.types import OutputReport
+
+done = client.jobs.get(job.id)
+
+for output in done.outputs:
+    if not output.HasField("report"):
+        continue  # not measured — never "nothing wrong"
+
+    report: OutputReport = output.report
+    print(
+        output.id,
+        report.video.codec,
+        f"{report.video.width}x{report.video.height}",
+        f"{report.duration_seconds}s",
+    )
+
+    if not report.verdict.matches_request:
+        for m in report.verdict.mismatches:
+            print(f"  {m.field}: asked for {m.expected}, got {m.actual}")
+```
+
+Check `output.HasField("report")` rather than truthiness: an absent report means
+"not measured", which is not the same as a report that found nothing wrong.
+Branch on `m.field` — it comes from a fixed vocabulary (`video.codec`,
+`video.resolution`, `duration_seconds`, …) — rather than on the values beside
+it. For an ABR ladder the facts describe the highest-resolution rendition, the
+same one the verdict judges; per-rendition detail stays in `variant_results`.
+
+An output encoded with per-title content-aware analysis also carries
+`report.content_aware`: the VMAF target the search aimed at, the score it reached
+on its samples, and the CRF it chose. It describes the SEARCH, not the delivered
+file — `vmaf_achieved` scores short samples taken before the real encode, which
+is never scored itself. Check `report.HasField("content_aware")`; an ordinary
+output has none.
+
 ## AI captions
 
 Add auto-generated captions to any output with a `generate` subtitle track. Leave `language` empty (or set `"auto"`) to auto-detect the spoken language, or pass an ISO 639-2 code to force one. A per-job fee is metered by source minute and surfaced on `job.fees`; produced captions appear on `job.subtitle_results` with `auto_generated=True`.
@@ -82,9 +127,13 @@ client.jobs            # create / get / list / cancel / confirm / watch
 client.videos          # upload helpers, multipart, create_from_url, get / list / update / delete / watch, get_stats / list_top_videos
 client.presets         # create / get / get_by_slug / list / update / duplicate / archive
 client.origins         # create / get / list / update / validate / archive
+client.ingest_rules    # create / get / list / update / delete / list_events / test / replay_event
 client.apps            # create / get / list / update / archive / enable_hosting
 client.api_keys        # create / get / list / revoke
 client.organizations   # create / get / list / update / check_slug
+client.billing         # list_invoices / retrieve / retrieve_upcoming / retrieve_profile / create_portal_session
+                       #   + retrieve_budget / set_budget / clear_budget
+                       #   + retrieve_outstanding_balance / settle_outstanding_balance
 client.memberships     # list / get / update_role / remove
 client.users           # get_me / get / list / update_me
 client.health          # check
@@ -229,6 +278,120 @@ r2 = {
 
 Provide either `account_id` or `endpoint`, never both. `jurisdiction` only applies when `account_id` is set.
 
+## Ingest rules
+
+An ingest rule is a standing instruction on one readable origin: *when an object
+matching these filters lands, create this job for it*. Your storage provider
+posts its object-created events to the rule's endpoint, and no server of yours
+is in the path. Amazon S3 via SNS, Google Cloud Storage via a Pub/Sub push
+subscription, Supabase Storage via a database webhook, and a generic shape for
+anything else are all recognised from the payload.
+
+```python
+created = client.ingest_rules.create(
+    origin_id="ori_a1b2c3d4e5f6",
+    name="Watch uploads/",
+    filters={
+        "prefix": "uploads/",
+        "suffixes": [".mp4", ".mov"],
+        "min_bytes": 1024,  # ignore the zero-byte placeholder some clients write first
+    },
+    action={
+        "outputs": [{"preset": "web_1080p_standard"}],
+        "managed": True,  # host and deliver the result; use output_origin_id for your own bucket
+        "priority": "standard",
+    },
+)
+
+print("point your bucket notifications at", created.rule.endpoint_url)
+print("secret (shown once):", created.secret)
+```
+
+`created.secret` is the **only** time the inbound secret is readable — store it
+wherever the event sender will read it from. A later `get` returns just
+`secret_prefix` and `secret_hint`. Lost it? `update` with `rotate_secret=True`
+issues a new one, and the previous one keeps working for 24 hours so the sender
+can be changed without dropping an event.
+
+Every delivery is recorded, whether or not it became a job:
+
+```python
+for event in client.ingest_rules.list_events(rule_id=created.rule.id).auto_paging_iter():
+    print(event.id, event.object_key, event.status, event.reason)
+```
+
+A `skipped` event names why in `reason` — `filter_prefix`, `filter_suffix`,
+`filter_content_type`, `filter_size`, `bucket_mismatch`, `rule_disabled`, or
+`duplicate`. A `failed` one carries the API error code that refused the job,
+such as `limit_exceeded`. Narrow the log to either with the simplified status
+string: `list_events(status="skipped")`.
+
+Deduplication is permanent: an object is identified by (rule, bucket, key,
+etag), so re-sending the event or re-uploading the same bytes produces nothing.
+To give an object another pass — one that arrived while the rule was paused, or
+was refused while the account was over its cap — replay it:
+
+```python
+replayed = client.ingest_rules.replay_event("sev_a1b2c3d4e5f6g7")
+print(replayed.id, "is back in", StorageEventStatus.Name(replayed.status))
+```
+
+Only `skipped` and `failed` events can be replayed. When an `update` switches a
+paused rule back on, the response reports how large that backlog is in
+`events_skipped_while_disabled`.
+
+Before wiring the provider up, dry-run a key against the rule with
+`client.ingest_rules.test(...)`: it reports whether the filters match and, when
+they do, the exact job request the rule would submit. Nothing is stored.
+
+## Billing
+
+Billing settles a whole organization, so `client.billing` needs a dashboard session token for an
+organization **owner** plus the organization it is for — an API key is scoped to one app and is
+rejected outright:
+
+```python
+client = Transcodely("tk_session_token", organization_id="org_f6g7h8i9j0")
+
+client.billing.retrieve_upcoming()  # what the current period has accrued
+client.billing.list_invoices(limit=12)
+```
+
+Three numbers live here and they are not interchangeable:
+
+| Call | What it answers | Enforces? |
+|---|---|---|
+| `billing.retrieve_upcoming()` | What the **current period** has accrued | No |
+| `billing.retrieve_budget()` | Spend against the org's own monthly budget | No — emails only |
+| `billing.retrieve_outstanding_balance()` | What is **unsettled**, incl. earlier periods | Yes, at the hard stop |
+| `apps.set_spend_limit(app_id, eur)` | One app's monthly cap | Yes, at 100% |
+
+Budgets notify; limits block:
+
+```python
+client.billing.set_budget(500.0)  # emails at 50% / 80% / 100%, restricts nothing
+client.billing.clear_budget()  # turns the alerts off
+```
+
+The outstanding balance is the platform's own exposure control. Reminder emails go out at 80%,
+100%, 125%, 150% and 175% of `threshold_cents` and restrict nothing; only at `hard_stop_cents`
+(twice the threshold) are **new** jobs refused with code `outstanding_balance_exceeded` — queued
+and running work still finishes and videos keep playing. Paying lifts the block on the next
+request:
+
+```python
+balance = client.billing.retrieve_outstanding_balance()
+if balance.blocked and balance.settlement_available:
+    result = client.billing.settle_outstanding_balance()
+    print(result.settlement.invoice_id, result.balance.outstanding_cents)  # → 0
+```
+
+Check `settlement_available` before offering a "pay now" action: settlement raises
+`PreconditionError` with code `settlement_unavailable` where the rail is switched off, and
+`nothing_outstanding` when there is nothing to pay. Job creates refused for money reasons carry
+`billing_past_due` (a statement is unpaid) or `outstanding_balance_exceeded` (too much unbilled
+usage) — neither clears by retrying, so back-off is the wrong response to both.
+
 ## Errors
 
 All exceptions inherit from `TranscodelyError`:

{transcodely-0.3.7 → transcodely-0.3.9}/pyproject.toml

@@ -4,14 +4,16 @@ build-backend = "hatchling.build"
 
 [project]
 name = "transcodely"
-version = "0.3.7"
-description = "Official Python SDK for the Transcodely video transcoding API"
+version = "0.3.9"
+description = "Official Python SDK for Transcodely — encode video to HLS, DASH and MP4 into your own S3, GCS or R2 bucket, with DRM and signed playback."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Transcodely" }]
 requires-python = ">=3.10"
-keywords = ["transcodely", "video", "transcoding", "encoding", "hls", "dash", "streaming", "connect-rpc"]
+keywords = ["transcodely", "video", "transcoding", "encoding", "hls", "dash", "cmaf",
+            "drm", "widevine", "fairplay", "abr", "ffmpeg", "s3", "r2", "signed-urls",
+            "video-hosting", "streaming", "connect-rpc"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
@@ -42,8 +44,8 @@ dev = [
 ]
 
 [project.urls]
-Homepage = "https://transcodely.com"
-Documentation = "https://transcodely.com/docs"
+Homepage = "https://www.transcodely.com"
+Documentation = "https://www.transcodely.com/docs"
 Repository = "https://github.com/transcodely/transcodely-python"
 Issues = "https://github.com/transcodely/transcodely-python/issues"
 

{transcodely-0.3.7 → transcodely-0.3.9}/src/transcodely/__init__.py

@@ -67,6 +67,7 @@ from .types import (
     DRMConfig,
     HDRConfig,
     HLSConfig,
+    IngestRule,
     Invoice,
     InvoiceLineItem,
     InvoiceLineType,
@@ -85,6 +86,9 @@ from .types import (
     Preset,
     PresetVariant,
     Resolution,
+    StorageEvent,
+    StorageEventSource,
+    StorageEventStatus,
     StreamingConfig,
     SubtitleResult,
     SubtitleTrack,
@@ -149,6 +153,7 @@ __all__ = [
     "FieldViolation",
     "HDRConfig",
     "HLSConfig",
+    "IngestRule",
     "InvalidRequestError",
     "Invoice",
     "InvoiceLineItem",
@@ -174,6 +179,9 @@ __all__ = [
     "PresetVariant",
     "RateLimitError",
     "Resolution",
+    "StorageEvent",
+    "StorageEventSource",
+    "StorageEventStatus",
     "StreamingConfig",
     "SubtitleResult",
     "SubtitleTrack",

{transcodely-0.3.7 → transcodely-0.3.9}/src/transcodely/client.py

@@ -13,6 +13,7 @@ from .resources.apps import Apps
 from .resources.billing import Billing
 from .resources.events import Events
 from .resources.health import Health
+from .resources.ingest_rules import IngestRules
 from .resources.jobs import Jobs
 from .resources.memberships import Memberships
 from .resources.organizations import Organizations
@@ -63,6 +64,7 @@ class Transcodely:
         self._videos: Videos | None = None
         self._presets: Presets | None = None
         self._origins: Origins | None = None
+        self._ingest_rules: IngestRules | None = None
         self._apps: Apps | None = None
         self._api_keys: ApiKeys | None = None
         self._organizations: Organizations | None = None
@@ -111,6 +113,13 @@ class Transcodely:
             self._origins = Origins(self._transport)
         return self._origins
 
+    @property
+    def ingest_rules(self) -> IngestRules:
+        """Ingest rules: watch a bucket, transcode what lands in it."""
+        if self._ingest_rules is None:
+            self._ingest_rules = IngestRules(self._transport)
+        return self._ingest_rules
+
     @property
     def apps(self) -> Apps:
         if self._apps is None: