Skip to main content

vCon Library

A Python library for working with vCon (Virtual Conversation) objects according to the vCon specification, currently draft-ietf-vcon-vcon-core-05 (syntax "0.5.0").

Documentation · API docs · Changelog · Migration guide · Source

pip install vcon

Requires Python 3.12 or later. Version 1.0 writes vCon syntax "0.5.0" and reads both "0.4.0" and "0.5.0"; a 0.4.0 vCon is migrated to 0.5.0 when it is loaded. 1.0 is a breaking release: read the migration guide before upgrading from 0.10 or earlier.

Overview

The vCon library provides a complete implementation of the vCon format for representing conversations and related metadata. It supports all features defined in the latest vCon specification including:

  • Conversation Management: Parties, dialogs, attachments, and analysis
  • Contact Information: Multiple contact methods (tel, email, SIP, DID)
  • Media Support: Recordings (audio and video), text, and images
  • Security: Digital signatures and content hashing
  • Extensibility: Extensions and critical fields
  • Location Data: Civic address information (GEOPRIV)
  • Sessions and Events: sessions group dialog by conversation, events record joins, drops, holds, key presses and call transfers
  • Migration: migrate_0_4_0_to_0_5_0() upgrades 0.4.0 vCons, with a report of everything it inferred
  • Privacy Compliance: Lawful Basis extension for GDPR compliance
  • Transcription Support: WTF (World Transcription Format) extension for standardized speech-to-text

Quick Start

Basic vCon Creation

from vcon import Vcon
from vcon.party import Party
from vcon.dialog import Dialog
from vcon.session import Session
from datetime import datetime, timezone

# Create a new vCon
vcon = Vcon.build_new()

# Add parties
caller = Party(tel="+1234567890", name="Alice", role="caller")
agent = Party(tel="+1987654321", name="Bob", role="agent")
vcon.add_party(caller)
vcon.add_party(agent)

# A Session groups the dialog of one conversation. Its parties are the
# receivers; each Dialog's parties are only the contributors.
vcon.add_session(Session(start=datetime.now(timezone.utc), parties=[0, 1]))

# Add dialog (to Session 0)
dialog = Dialog(
    type="text",
    start=datetime.now(timezone.utc),
    parties=[0],
    body="Hello, I need help with my account.",
    encoding="none",
    mediatype="text/plain",
)
vcon.add_dialog(dialog, session=0)

# Save to file
vcon.save_to_file("conversation.vcon.json")
print(f"Created vCon: {vcon.uuid}")  # syntax "0.5.0"

Loading a 0.4.0 vCon

# Readers accept 0.4.0 and 0.5.0. A document that declares "vcon": "0.4.0"
# is migrated to 0.5.0 on load; the report lists every inferred value.
vcon = Vcon.load("old.vcon.json")
print(vcon.migration_report.summary())   # "3 inferred, 0 fallback, 1 unresolved"

# Or migrate explicitly (strict=True raises MigrationError instead of using a fallback)
from vcon import migrate_0_4_0_to_0_5_0
new_dict, report = migrate_0_4_0_to_0_5_0(old_dict, strict=False)

Privacy Compliance with Lawful Basis Extension

from datetime import timedelta

# Add lawful basis for consent
vcon.add_lawful_basis_attachment(
    lawful_basis="consent",
    expiration=(datetime.now(timezone.utc) + timedelta(days=365)).isoformat(),
    purpose_grants=[
        {
            "purpose": "recording",
            "granted": True,
            "granted_at": datetime.now(timezone.utc).isoformat()
        },
        {
            "purpose": "transcription",
            "granted": True,
            "granted_at": datetime.now(timezone.utc).isoformat()
        }
    ],
    party_index=0
)

# Check permissions
can_record = vcon.check_lawful_basis_permission("recording", party_index=0)
print(f"Can record: {can_record}")

Transcription with WTF Extension

# Add transcription
vcon.add_wtf_transcription_attachment(
    transcript={
        "text": "Hello, I need help with my account.",
        "language": "en",
        "duration": 4.2,
        "confidence": 0.92
    },
    segments=[
        {
            "id": 0,
            "start": 0.0,
            "end": 4.2,
            "text": "Hello, I need help with my account.",
            "confidence": 0.92,
            "speaker": 0
        }
    ],
    metadata={
        "created_at": datetime.now(timezone.utc).isoformat(),
        "processed_at": datetime.now(timezone.utc).isoformat(),
        "provider": "whisper",
        "model": "whisper-1"
    },
    party_index=0,
    dialog_index=0
)

# Export to SRT format
attachments = vcon.find_wtf_attachments(party_index=0)
if attachments:
    from vcon.extensions.wtf import WTFAttachment
    wtf_attachment = WTFAttachment.from_dict(attachments[0]["body"])
    srt_content = wtf_attachment.export_to_srt()
    print("SRT Export:")
    print(srt_content)

Complete Example with Extensions

# Create comprehensive vCon with extensions
vcon = Vcon.build_new()

# Add parties
caller = Party(tel="+1234567890", name="Alice", role="caller")
agent = Party(tel="+1987654321", name="Bob", role="agent")
vcon.add_party(caller)
vcon.add_party(agent)

# One Session for the call, then the recording dialog in it
vcon.add_session(Session(start=datetime.now(timezone.utc), parties=[0, 1]))
dialog = Dialog(
    type="recording",
    start=datetime.now(timezone.utc),
    parties=[0, 1],
    mediatype="audio/mp3"
)
vcon.add_dialog(dialog, session=0)

# Add lawful basis for consent
vcon.add_lawful_basis_attachment(
    lawful_basis="consent",
    expiration=(datetime.now(timezone.utc) + timedelta(days=365)).isoformat(),
    purpose_grants=[
        {
            "purpose": "recording",
            "granted": True,
            "granted_at": datetime.now(timezone.utc).isoformat()
        },
        {
            "purpose": "transcription",
            "granted": True,
            "granted_at": datetime.now(timezone.utc).isoformat()
        }
    ],
    party_index=0
)

# Add transcription
vcon.add_wtf_transcription_attachment(
    transcript={
        "text": "Hello, I need help with my account.",
        "language": "en",
        "duration": 4.2,
        "confidence": 0.92
    },
    segments=[
        {
            "id": 0,
            "start": 0.0,
            "end": 4.2,
            "text": "Hello, I need help with my account.",
            "confidence": 0.92,
            "speaker": 0
        }
    ],
    metadata={
        "created_at": datetime.now(timezone.utc).isoformat(),
        "processed_at": datetime.now(timezone.utc).isoformat(),
        "provider": "whisper",
        "model": "whisper-1"
    },
    party_index=0,
    dialog_index=0
)

# Add extensions
vcon.add_extension("lawful_basis")
vcon.add_extension("wtf_transcription")

# Validate extensions
validation_results = vcon.validate_extensions()
print("Extension validation:", validation_results)

# Save vCon
vcon.save_to_file("complete_conversation.vcon.json")
print(f"Created complete vCon with extensions: {vcon.uuid}")

Key Features

This library implements the latest vCon specification with the following features:

Enhanced Party Information

from vcon import Vcon
from vcon.party import Party

# Create a party with enhanced contact information
party = Party(
    tel="+1234567890",
    name="John Doe",
    sip="sip:john@example.com",
    did="did:example:123456789abcdef",
    jCard={
        "fn": "John Doe",
        "tel": "+1234567890",
        "email": "john@example.com"
    },
    timezone="America/New_York"
)

Extensions and Must-Support

vcon = Vcon.build_new()

# Add extensions used in this vCon
vcon.add_extension("video")
vcon.add_extension("encryption")

# Add extensions that must be supported
vcon.add_critical("encryption")

print(vcon.get_extensions())  # ['video', 'encryption']
print(vcon.get_critical())  # ['encryption']

Enhanced Dialog Support

from vcon.dialog import Dialog
from datetime import datetime

# Create dialog with new fields
dialog = Dialog(
    type="text",
    start=datetime.now(),
    parties=[0, 1],
    session_id={"local": "local-uuid", "remote": "remote-uuid"},
    # "<algorithm>-<unpadded base64url digest>"; vcon.compute_content_hash(data) makes one
    content_hash="sha512-xbxzWUN7HoME4TkKebyfothmuRRH1M_Skvg2tfVxlFDWSQOdsLcKZ60qsibswilp_NsnfnBW3-7ctRSQGT9UVg",
    application="chat-app",
    message_id="<message-id@example.com>"
)

Events (replacing party history)

from vcon.event import Event
from datetime import datetime, timezone

now = datetime.now(timezone.utc)
# Events apply to the Sessions listed in `sessions`.
vcon.add_event(Event(type="join", time=now, sessions=0, party=0))
vcon.add_event(Event(type="hold", time=now, sessions=0, party=0))
vcon.add_event(Event(type="keydown", time=now, sessions=0, party=1, button="5"))

# A blind transfer: `sessions` is the original call, `target_session` the call to the target
vcon.add_event(Event(type="blind-transfer", time=now, sessions=0, party=1,
                     transferee=0, transfer_target=2, target_session=1))

Each type has a parameter table (core-05 section 4.3.1.5) that Event and Vcon.is_valid() enforce: required (M), optional (O), should not (SN, a warning) and must not (X).

Sessions

from vcon.session import Session, SessionReference

vcon.add_session(Session(
    start=now, duration=300, parties=[0, 1],   # parties are the receivers
    originator=1,                              # only when not the first party
    sessions=[SessionReference(1, "child")],   # child, peer, precursor, breakout
))
vcon.add_session()   # an empty placeholder Session is allowed

Disposition Values for Incomplete Dialogs

# Create incomplete dialog with proper disposition
incomplete_dialog = Dialog(
    type="incomplete",
    start=datetime.now(),
    parties=[0],
    disposition="no-answer"  # Valid: no-answer, congestion, failed, busy, hung-up, voicemail-no-message
)

Civic Address Support

from vcon.civic_address import CivicAddress

# Create civic address with GEOPRIV fields
address = CivicAddress(
    country="US",
    a1="CA",
    a3="San Francisco",
    sts="Market Street",
    hno="123",
    pc="94102"
)

party = Party(name="Jane", civicaddress=address)

Lawful Basis Extension (Privacy Compliance)

from datetime import datetime, timezone, timedelta

# Add lawful basis for GDPR compliance
vcon.add_lawful_basis_attachment(
    lawful_basis="consent",
    expiration=(datetime.now(timezone.utc) + timedelta(days=365)).isoformat(),
    purpose_grants=[
        {
            "purpose": "recording",
            "granted": True,
            "granted_at": datetime.now(timezone.utc).isoformat()
        },
        {
            "purpose": "analysis",
            "granted": True,
            "granted_at": datetime.now(timezone.utc).isoformat(),
            "conditions": ["anonymized_data_only"]
        }
    ],
    party_index=0,
    session_index=0   # an attachment needs a dialog or session scope
)

# Check permissions
can_record = vcon.check_lawful_basis_permission("recording", party_index=0)
can_analyze = vcon.check_lawful_basis_permission("analysis", party_index=0)

# Find lawful basis attachments
attachments = vcon.find_lawful_basis_attachments(party_index=0)

WTF Extension (Transcription Support)

# Add standardized transcription
vcon.add_wtf_transcription_attachment(
    transcript={
        "text": "Hello, this is a test transcription.",
        "language": "en",
        "duration": 3.5,
        "confidence": 0.95
    },
    segments=[
        {
            "id": 0,
            "start": 0.0,
            "end": 1.5,
            "text": "Hello, this is",
            "confidence": 0.95,
            "speaker": 0
        },
        {
            "id": 1,
            "start": 1.5,
            "end": 3.5,
            "text": "a test transcription.",
            "confidence": 0.94,
            "speaker": 0
        }
    ],
    metadata={
        "created_at": datetime.now(timezone.utc).isoformat(),
        "processed_at": datetime.now(timezone.utc).isoformat(),
        "provider": "whisper",
        "model": "whisper-1"
    },
    party_index=0,
    dialog_index=0
)

# Export to subtitle formats
attachments = vcon.find_wtf_attachments(party_index=0)
if attachments:
    from vcon.extensions.wtf import WTFAttachment
    wtf_attachment = WTFAttachment.from_dict(attachments[0]["body"])
    
    # Export to SRT format
    srt_content = wtf_attachment.export_to_srt()
    
    # Export to WebVTT format
    vtt_content = wtf_attachment.export_to_vtt()

Provider Data Conversion

from vcon.extensions.wtf import WhisperAdapter, DeepgramAdapter

# Convert Whisper data to WTF format
whisper_data = {
    "text": "Hello world from Whisper",
    "segments": [
        {
            "start": 0.0,
            "end": 2.0,
            "text": "Hello world from Whisper"
        }
    ]
}

whisper_adapter = WhisperAdapter()
wtf_attachment = whisper_adapter.convert(whisper_data)

# Add to vCon
vcon.add_wtf_transcription_attachment(
    transcript=wtf_attachment.transcript.to_dict(),
    segments=[segment.to_dict() for segment in wtf_attachment.segments],
    metadata=wtf_attachment.metadata.to_dict(),
    party_index=0,
    session_index=0
)

Installation

pip install vcon

Basic Usage

Creating a vCon

from vcon import Vcon
from vcon.party import Party
from vcon.dialog import Dialog
from vcon.session import Session
from datetime import datetime

# Create a new vCon
vcon = Vcon.build_new()

# Add parties
alice = Party(tel="+1234567890", name="Alice", role="caller")
bob = Party(tel="+1987654321", name="Bob", role="agent")

vcon.add_party(alice)
vcon.add_party(bob)

# A Session lists the receivers; Dialog parties are the contributors
vcon.add_session(Session(start=datetime.now(), parties=[0, 1]))

# Add dialog
dialog = Dialog(
    type="text",
    start=datetime.now(),
    parties=[0],
    body="Hello, this is a test message!",
    encoding="none",
    mediatype="text/plain",
)

vcon.add_dialog(dialog, session=0)

# Save to file
vcon.save_to_file("conversation.vcon.json")

Loading a vCon

# Load from file
vcon = Vcon.load("conversation.vcon.json")

# Load from URL
vcon = Vcon.load("https://example.com/conversation.vcon.json")

Validation

# Validate a vCon
is_valid, errors = vcon.is_valid()

if is_valid:
    print("vCon is valid")
else:
    print("Validation errors:", errors)

# Validate from file
is_valid, errors = Vcon.validate_file("conversation.vcon.json")

Media Support

Audio and Video

Core-05 has three Dialog types: recording, text and incomplete. Audio and video are both recording Dialogs, told apart by mediatype. Dialog(type="audio") and Dialog(type="video") still work, but they warn and build a recording.

# Add audio recording
audio_dialog = Dialog(
    type="recording",
    start=datetime.now(),
    parties=[0, 1],
    url="https://example.com/recording.wav",
    mediatype="audio/x-wav"
)

# Add video with metadata
video_dialog = Dialog(
    type="recording",
    start=datetime.now(),
    parties=[0, 1],
    url="https://example.com/video.mp4",
    mediatype="video/mp4",
    resolution="1920x1080",
    frame_rate=30.0,
    codec="H.264"
)

Supported Media Types

Audio: audio/x-wav, audio/x-mp3, audio/x-mp4, audio/ogg Video: video/x-mp4, video/ogg Text: text/plain Multipart: multipart/mixed

Security Features

Digital Signatures

from cryptography.hazmat.primitives import serialization

# Generate key pair
private_key, public_key = Vcon.generate_key_pair()

# Sign the vCon (RS256 by default; alg "none" raises AlgorithmNotPermittedError)
vcon.sign(private_key)

# Verify signature
is_valid = vcon.verify(public_key)

Content Hashing

# Hash the dialog's content: "sha512-<unpadded base64url>" by default
content_hash = dialog.calculate_content_hash()

# Verify content integrity against a stored hash
is_valid = dialog.verify_content_hash(content_hash)

Advanced Features

Property Handling

# Strict mode - only allow standard properties
vcon = Vcon.load("file.json", property_handling="strict")

# Meta mode - move non-standard properties to meta object
vcon = Vcon.load("file.json", property_handling="meta")

# Default mode - keep all properties
vcon = Vcon.load("file.json", property_handling="default")

Call Transfers

The transfer dialog type was removed in 0.5.0. A transfer is one or two Events (consultation-start, blind-transfer, consultative-transfer, transfer-abandoned) that reference Sessions for the original, consultation and target calls. See "Events" above.

Empty Dialog Objects

# Holds a position in the dialog array so no other index moves
vcon.add_dialog(Dialog.placeholder())   # serializes as {}

Analysis Data

# Add analysis
vcon.add_analysis(
    type="sentiment",
    dialog=0,
    vendor="example-vendor",
    body={"sentiment": "positive", "confidence": 0.95},
    encoding="json"
)

Specification Compliance

This library implements the latest vCon specification with:

  • ✅ All required fields and validation
  • ✅ Proper media type support
  • ✅ Civic address (GEOPRIV) compliance
  • ✅ Sessions and Events, with the per-event-type parameter table enforced
  • ✅ Migration from 0.4.0 (migrate_0_4_0_to_0_5_0)
  • ✅ extensions completeness and alg: "none" rejection
  • ✅ Content hashing and security
  • ✅ Extensions and critical
  • ✅ Writes "vcon": "0.5.0"; reads 0.4.0 and 0.5.0
  • ✅ Backward compatibility
  • ✅ Lawful Basis Extension - GDPR-compliant privacy management
  • ✅ WTF Extension - World Transcription Format for standardized speech-to-text
  • ✅ Extension Framework - Comprehensive validation and processing
  • ✅ Multi-Provider Support - Whisper, Deepgram, AssemblyAI, and more
  • ✅ Export Capabilities - SRT and WebVTT subtitle formats

Testing

Run the test suite:

pytest tests/

All tests pass, covering:

  • Basic functionality
  • Enhanced vCon features
  • Validation and error handling
  • Media type support
  • Security features
  • Flexible versioning
  • Backward compatibility
  • Extension Framework - Lawful Basis and WTF extensions
  • Privacy Compliance - GDPR-compliant consent management
  • Transcription Support - Multi-provider transcription handling
  • Provider Adapters - Data conversion and validation
  • Export Functionality - SRT and WebVTT export testing

Extension Framework

The vCon library includes a comprehensive extension framework that allows for standardized implementation of additional functionality:

Available Extensions

  • Lawful Basis Extension - GDPR-compliant privacy management and consent tracking
  • WTF Extension - World Transcription Format for standardized speech-to-text data

Extension Features

  • Validation Framework - Comprehensive validation for all extension data
  • Processing Framework - Standardized processing and analysis
  • Provider Adapters - Automatic conversion from provider-specific formats
  • Export Capabilities - Multiple export formats (SRT, WebVTT)
  • Permission Management - Granular permission checking and validation

Extension Usage

# Validate all extensions
validation_results = vcon.validate_extensions()

# Process all extensions
processing_results = vcon.process_extensions()

# Check specific permissions
can_record = vcon.check_lawful_basis_permission("recording", party_index=0)

# Export transcriptions
attachments = vcon.find_wtf_attachments(party_index=0)

Documentation

License

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

Metadata

Release files for vcon 1.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vcon 1.0.3
File Size Uploaded Provenance Actions
vcon-1.0.3.tar.gz 97.6 kB Without provenance Details for vcon-1.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vcon 1.0.3
File Interpreter ABI Platform Actions
vcon-1.0.3-py3-none-any.whl Python 3 none any Details for vcon-1.0.3-py3-none-any.whl

Total release size: 203.1 kB

Release files / vcon-1.0.3.tar.gz

Download URL vcon-1.0.3.tar.gz
Size 97.6 kB
Tags Source
SHA-256 checksum
How to use checksums
ff1a2c0e0d718820b9988005ee7751f55b1f090f16d37d0b0ddac2e7787f2734
BLAKE2b-256 checksum
How to use checksums
ee811c435ee883ffffc57497daf9f71ea1868a81b2a4a4c09422d2c9d780006e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Release files / vcon-1.0.3-py3-none-any.whl

Download URL vcon-1.0.3-py3-none-any.whl
Size 105.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
28de362508aa64f3fd92ebd3372bd185da50f1c76f20655fb5b8e67adbe29fa0
BLAKE2b-256 checksum
How to use checksums
64aa3ab8b2d0ffd978bab2c280356949fffe4006be8cfb55adb7b957879b91cb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Security for vcon 1.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page