iscc-lib

High-performance polyglot implementation of ISO 24138:2024 — International Standard Content Code (ISCC)

Key Features

• Similarity-Preserving: Detect similar content even after modifications
• Multi-Level Identification: Identify content at metadata, semantic, perceptual, and data levels
• Self-Describing: Each component contains its own type and version information
• ISO Standardized: Implements the official ISO 24138:2024 specification
• Polyglot: Rust core with bindings for Python, Java, Go, Ruby, Node.js, WASM, and C FFI
• Conformance-Tested: Validated against the official iscc-core reference implementation

What is the ISCC

The ISCC is a similarity-preserving fingerprint and identifier for digital media assets.

ISCCs are generated algorithmically from digital content, just like cryptographic hashes. However, instead of using a single cryptographic hash function to identify data only, the ISCC uses various algorithms to create a composite identifier that exhibits similarity-preserving properties (soft hash).

The component-based structure of the ISCC identifies content at multiple levels of abstraction. Each component is self-describing, modular, and can be used separately or with others to aid in various content identification tasks. The algorithmic design supports content deduplication, database synchronization, indexing, integrity verification, timestamping, versioning, data provenance, similarity clustering, anomaly detection, usage tracking, allocation of royalties, fact-checking, and general digital asset management use-cases.

What is iscc-lib

iscc-lib is a high-performance polyglot implementation of the ISCC core algorithms (ISO 24138). Built in Rust with language bindings for Python, Java, Go, Ruby, Node.js, WebAssembly, and C, it serves developers across multiple ecosystems who need fast, reliable content identification.

iscc-lib is conformance-tested against the official Python reference implementation iscc-core and produces identical results for all test vectors.

Note: This is a low-level codec and algorithm library. It does not include features like media-type detection, metadata extraction, or file-format-specific content extraction. For higher-level features, see iscc-sdk which builds on top of the core algorithms.

ISCC Architecture

ISCC MainTypes

Idx	Slug	Bits	Purpose
0	META	0000	Match on metadata similarity
1	SEMANTIC	0001	Match on semantic content similarity
2	CONTENT	0010	Match on perceptual content similarity
3	DATA	0011	Match on data similarity
4	INSTANCE	0100	Match on data identity
5	ISCC	0101	Composite of two or more components with common header

Installation

Rust

cargo add iscc-lib

Python

pip install iscc-lib

Node.js

npm install @iscc/lib

Java

<dependency>
  <groupId>io.iscc</groupId>
  <artifactId>iscc-lib</artifactId>
  <version>0.2.0</version>
</dependency>

The native library must be available on java.library.path at runtime.

Go

go get github.com/iscc/iscc-lib/packages/go

Ruby

gem install iscc-lib

WASM

npm install @iscc/wasm

Quick Start

Rust

use iscc_lib::gen_meta_code_v0;

let result = gen_meta_code_v0("ISCC Test Document!", None, None, 64).unwrap();
println!("Meta-Code: {}", result.iscc);

Python

import iscc_lib as ic

result = ic.gen_meta_code_v0("ISCC Test Document!")
print(f"Meta-Code: {result['iscc']}")

Node.js

const ic = require("@iscc/lib");

const result = ic.gen_meta_code_v0("ISCC Test Document!");
console.log(`Meta-Code: ${result.iscc}`);

Java

import io.iscc.iscc_lib.IsccLib;

String result = IsccLib.genMetaCodeV0("ISCC Test Document!", null, null, 64);
System.out.println("Meta-Code: " + result);

Go

package main

import (
	"fmt"
	"log"

	iscc "github.com/iscc/iscc-lib/packages/go"
)

func main() {
	result, err := iscc.GenMetaCodeV0("ISCC Test Document!", nil, nil, 64)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Meta-Code:", result.Iscc)
}

Ruby

require "iscc_lib"

result = IsccLib.gen_meta_code_v0("ISCC Test Document!")
puts "Meta-Code: #{result.iscc}"

WASM

import {
    gen_meta_code_v0
} from "@iscc/wasm";

const result = gen_meta_code_v0("ISCC Test Document!");
console.log(`Meta-Code: ${result.iscc}`);

Implementors Guide

To build a conformant ISCC implementation, work through the following top-level entry-point functions:

gen_meta_code_v0
gen_text_code_v0
gen_image_code_v0
gen_audio_code_v0
gen_video_code_v0
gen_mixed_code_v0
gen_data_code_v0
gen_instance_code_v0
gen_iscc_code_v0
gen_sum_code_v0

The corresponding conformance test vectors can be found in iscc_core/data.json.

For detailed per-language API guides, see the documentation site.

Documentation

Documentation is published at https://lib.iscc.codes

Contributing

Pull requests are welcome. For significant changes, please open an issue first to discuss your plans. Please make sure to update tests as appropriate.

You may also want to join our developer chat on Telegram at https://t.me/iscc_dev.

License

Apache-2.0

Maintainers

@titusz