API Reference & Usage

from jpegtrust import embed_image

# From a JSON file
embed_image("photo.jpg", "metadata.json", "signed.jpg")

# From a Python dict
metadata = {
    "@context": ["https://jpeg.org/jpegtrust/"],
    "declaration": {
        "claim": {"alg": "sha256"},
        "assertions": {"c2pa.actions": {"actions": []}}
    }
}
embed_image("photo.jpg", metadata, "signed.jpg")

from jpegtrust import embed_metadata

with open("photo.jpg", "rb") as f:
    image_bytes = f.read()

metadata = {"@context": ["https://jpeg.org/jpegtrust/"], ...}

# Get bytes back
result = embed_metadata(image_bytes, metadata)

# Or write directly to disk
embed_metadata(image_bytes, metadata, output_path="signed.jpg")

from jpegtrust import extract_from_file

indicator = extract_from_file("signed.jpg")

if indicator is None:
    print("No metadata found")
else:
    print(indicator["declaration"]["claim"]["alg"])  # "sha256"
    print(indicator["manifests"][0]["assertions"])    # {...}

import json
from jpegtrust import extract_metadata

with open("signed.jpg", "rb") as f:
    raw = extract_metadata(f.read())

if raw:
    data = json.loads(raw)
    print(json.dumps(data, indent=2))

from jpegtrust import verify_image

report = verify_image("signed.jpg", "policy.yml")

print(f"Status:  {report.status}")      # "pass" | "warning" | "fail"
print(f"Score:   {report.score}")       # 0.0 - 1.0
print(f"Verdict: {report.verdict}")     # "trusted" | "mostly_trusted" | "profile_mismatch"
print(f"Passed:  {report.passed_checks}/{report.total_checks}")
print(f"Failed:  {report.failed}")

# Convert to dict for JSON serialization
result_dict = report.to_dict()

from jpegtrust import verify, extract_from_file, load_profile

# Step 1: extract the indicator
indicator = extract_from_file("signed.jpg")

# Step 2: load the profile YAML
profile_yaml = load_profile("policy.yml")

# Step 3: verify
report = verify(indicator, profile_yaml)
print(report.status, report.score)

from jpegtrust import create_profile, save_profile

# From a template
profile = create_profile(template="newsroom", name="AP Wire Photo Policy")
save_profile(profile, "newsroom.yml")

# Custom: pick specific checks
profile = create_profile(
    check_ids=["signature_chain", "pixel_hash", "copyright"],
    name="Licensing Policy",
    issuer="My Platform",
)
save_profile(profile, "licensing.yml")

from jpegtrust import list_templates

for name, check_ids in list_templates().items():
    print(f"{name}: {len(check_ids)} checks")

# Output:
# newsroom: 11 checks
# insurance: 6 checks
# creator: 6 checks
# ai-labelling: 7 checks
# custom: 0 checks

from jpegtrust import list_checks

for check in list_checks():
    print(f"{check.id:24s} [{check.level:8s}] {check.label}")

# Output:
# signature_chain          [required] Signature chain
# capture_timestamp        [required] Capture timestamp
# author_identity          [required] Author identity
# edit_history             [required] Edit history
# ai_declaration           [required] AI declaration
# gps_location             [optional] GPS / location
# copyright                [optional] Copyright / licence
# data_mining              [optional] Data mining declaration
# pixel_hash               [required] Pixel hash binding
# digital_source_type      [required] Digital source type
# ai_labelling             [optional] AI labelling

from jpegtrust import batch_embed

outputs = batch_embed("./photos", "metadata.json", "./signed")
print(f"Embedded {len(outputs)} images")

# With a custom pattern
outputs = batch_embed("./photos", "metadata.json", "./signed", pattern="*.jpeg")

from jpegtrust import batch_extract

# Just get the data
results = batch_extract("./signed")
for r in results:
    if r["metadata"]:
        print(f"{r['filename']}: has metadata")

# Also write JSON files
results = batch_extract("./signed", output_dir="./extracted")

import sys
from jpegtrust import batch_verify

result = batch_verify("./uploads", "policy.yml")

summary = result["summary"]
print(f"Total: {summary['total']}")
print(f"Passed: {summary['passed']}")
print(f"Failed: {summary['failed']}")

# Use in CI: fail if any image doesn't pass
if summary["failed"] > 0 or summary["errors"] > 0:
    sys.exit(1)