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:
sessionsgroup dialog by conversation,eventsrecord 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_analysis(
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"
},
dialog_index=0
)
# Export to SRT format
entry = vcon.find_analysis_by_type("wtf_transcription")
if entry:
from vcon.extensions.wtf import WTFAttachment
wtf_attachment = WTFAttachment.from_dict(Vcon.decoded_body(entry))
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_analysis(
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"
},
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_analysis(
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"
},
dialog_index=0
)
# Export to subtitle formats
entry = vcon.find_analysis_by_type("wtf_transcription")
if entry:
from vcon.extensions.wtf import WTFAttachment
wtf_attachment = WTFAttachment.from_dict(Vcon.decoded_body(entry))
# 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_analysis(
transcript=wtf_attachment.transcript.to_dict(),
segments=[segment.to_dict() for segment in wtf_attachment.segments],
metadata=wtf_attachment.metadata.to_dict(),
session_index=0
)
Installation
pip install vcon
pip install "vcon[image]" # image and PDF helpers (Pillow, pypdf)
pip install "vcon[video]" # video metadata, thumbnails and transcoding (ffmpeg-python; needs the ffmpeg binary)
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) - ✅
extensionscompleteness andalg: "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)
# Find transcriptions
transcripts = [a for a in vcon.analysis if a["type"] == "wtf_transcription"]
Documentation
- conserver.io: vCon Library - Quickstart and API reference
- API docs - Generated from the source
- API Reference - Complete API documentation
- User Guide - Comprehensive usage guide
- LLM Guide - Guide for AI-assisted development
- Migration Guide - Upgrading from 0.10 and earlier
- Changelog - Release notes
License
This project is licensed under the MIT License - see the LICENSE file for details.
Metadata
Release files for vcon 1.0.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vcon-1.0.5.tar.gz | 101.9 kB | Without provenance | Details for vcon-1.0.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vcon-1.0.5-py3-none-any.whl | Python 3 | none | any | Details for vcon-1.0.5-py3-none-any.whl |
Total release size: 211.5 kB
Release files / vcon-1.0.5.tar.gz
| Download URL | vcon-1.0.5.tar.gz |
|---|---|
| Size | 101.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
45c62388b48ecba4ccbbdaba28df8f3e4876c1c55e3c555770ada8260addd201
|
|
BLAKE2b-256 checksum How to use checksums |
42263ad201d8e70f582fa554952c859415a15b466c9f9ef690269304f33a4949
|
| 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.5-py3-none-any.whl
| Download URL | vcon-1.0.5-py3-none-any.whl |
|---|---|
| Size | 109.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
af577b6d7ac6320161f43118f1a2cf60b69ab6b735334e9d4ac4ef6459230903
|
|
BLAKE2b-256 checksum How to use checksums |
62e9d2687e0f5949bae4f82ce554e8ab81e66c8fc64d83ed49c4fd5d263c2427
|
| 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.5
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.