ISCC Software Development Kit (iscc-sdk)

A comprehensive Python toolkit for creating and managing ISCC (International Standard Content Code) identifiers for digital media assets.

Overview

What is an ISCC?

The International Standard Content Code (ISCC) is a content-dependent, similarity-preserving identifier and fingerprint system for digital content, standardized as ISO 24138:2024.

ISCCs are neither manually nor automatically assigned but are derived from the digital content itself. Generated algorithmically using various hash algorithms, ISCCs create composite identifiers with similarity-preserving properties (soft hashes) that can be independently derived by unrelated parties from the same media asset.

Digital content is dynamic - continuously re-encoded, resized, and re-compressed as it travels through complex networks. The ISCC remains robust across these transformations while preserving estimates of data, content, and metadata similarity.

The component-based structure of ISCC identifies content at multiple levels of abstraction, creating a multi-layered fingerprint. These components work together to create a robust, similarity-preserving identifier that remains stable despite modifications to the underlying digital asset. With this multi-layered approach, the ISCC can track content throughout its lifecycle, even as it's re-encoded, resized, or re-compressed.

Each component is self-describing, modular, and can be used separately or together, enabling ISCCs to support numerous digital asset management use-cases across all domains concerned with producing, processing, and distributing digital information (science, journalism, books, music, film, etc.):

• Content deduplication and discovery
• Database synchronization and indexing
• Integrity verification and timestamping
• Versioning and data provenance tracking
• Similarity clustering and matching
• Anomaly detection in content collections
• Usage tracking and royalty allocation
• Fact-checking and content verification
• Interoperability between different systems and actors
• Association with higher-level identifiers (work/product identifiers)

What is iscc-sdk?

iscc-sdk builds on top of iscc-core to provide high-level features for generating and handling ISCC codes across different media types. It serves as a complete toolkit for implementing ISCC-based workflows in Python applications.

Features

• Comprehensive Media Support: Process text, image, audio, and video files
• Mediatype Detection: Automatically identify file formats
• Metadata Management: Extract and embed metadata across different file formats
• Content Processing: Handle mediatype-specific content extraction and normalization
• Rich CLI: Command-line interface for easy integration into workflows
• Cross-Platform: Works on Windows, macOS, and Linux
• Built-in Tools: Includes necessary binaries for media processing
• Standards Compliant: Build on top of the ISO 24138:2024 reference implementation

Requirements

• Python 3.11 to 3.14 on 64-bit systems
• Supported platforms: Windows, macOS, Linux

Installation

Using pip

pip install iscc-sdk

Using uv

uv add iscc-sdk

Usage

Python API

Create an ISCC-CODE for a media file:

import iscc_sdk as idk

# Generate a complete ISCC code
iscc_meta = idk.code_iscc("/path/to/mediafile.jpg")
print(iscc_meta.iscc)  # Full ISCC code
print(iscc_meta.json(indent=2))  # All metadata as JSON

# Generate specific ISCC components
meta_code = idk.code_meta("/path/to/mediafile.jpg")
content_code = idk.code_content("/path/to/mediafile.jpg")
data_code = idk.code_data("/path/to/mediafile.jpg")
instance_code = idk.code_instance("/path/to/mediafile.jpg")

# Process specific media types
text_code = idk.code_text("/path/to/document.pdf")
image_code = idk.code_image("/path/to/image.png")
audio_code = idk.code_audio("/path/to/audio.mp3")
video_code = idk.code_video("/path/to/video.mp4")

Extract and embed metadata:

import iscc_sdk as idk
from iscc_schema import IsccMeta

# Extract metadata
metadata = idk.extract_metadata("/path/to/mediafile.jpg")

# Create custom metadata
custom_meta = IsccMeta(
    name="My Asset Title",
    description="Description of the asset",
    creator="Creator Name",
    license="https://creativecommons.org/licenses/by/4.0/",
)

# Embed metadata into a copy of the file
new_file = idk.embed_metadata("/path/to/mediafile.jpg", custom_meta)

Command Line Interface

The SDK includes a command-line interface called iscc-sdk.

Create an ISCC code for a single file:

iscc-sdk create /path/to/mediafile.jpg

Process multiple files in a directory:

iscc-sdk batch /folder_with_media_files

Install required binaries:

iscc-sdk install

Run self-tests:

iscc-sdk selftest

Documentation

For complete documentation, visit https://sdk.iscc.codes

Project Status

The ISCC is an official standard published as ISO 24138:2024 - International Standard Content Code within ISO/TC 46/SC 9/WG 18.

Note: The iscc-sdk library and the accompanying documentation are under active development. API changes and other backward incompatible changes are to be expected until a v1.0 stable release.

Development

Setup

# Install dependencies
uv sync

# Install pre-commit hooks (using prek, a fast Rust-based drop-in replacement)
uv tool install prek
prek install
prek install --hook-type pre-push

Quality Gates

Pre-commit hooks run automatically via prek:

On commit (fast, auto-fix):

• File hygiene (line endings, trailing whitespace, EOF)
• Config validation (YAML, JSON, TOML)
• Markdown formatting (mdformat)
• Ruff linting with auto-fix
• Ruff formatting

On push (thorough):

• Type checking (zuban)
• Security scan (Ruff S rules)
• Complexity check (Ruff C901)
• Tests with 100% coverage

Run all hooks manually:

prek run --all-files                # pre-commit hooks
prek run --all-files --hook-stage pre-push  # pre-push hooks

Testing

uv run pytest --cov=iscc_sdk --cov-fail-under=100 -p no:warnings

Contributing

Contributions are welcome! Here's how you can help:

1. Issues: Report bugs or suggest features via the issue tracker
2. Pull Requests: Submit PRs for bug fixes or new features
3. Discussion: For significant changes, please open an issue first to discuss your plans
4. Testing: Please make sure to update tests as appropriate

Join our developer chat on Telegram at https://t.me/iscc_dev.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.