🐰Quickstart

The Python vCon library

vCon Library

A Python library for working with vCon (Virtual Conversation) objects according to the vCon specification.

Current version: vcon 0.9.4 (May 2026). Install with pip install vcon.

Spec target: draft-ietf-vcon-vcon-core-02 Β· syntax parameter "vcon": "0.4.0".

Recent releases

0.9.4 β€” Security: dependency bumps for authlib, requests, pydash, python-dateutil, mutagen, pypdf, pillow, uuid6.

0.9.3 β€” Fixed: Vcon.add_tag() now correctly includes party: 0 and dialog: 0 on the created tags-purpose attachment. Previously the attachment was missing these spec-required indices.

0.9.2 β€” Spec compliance pass:

  • build_new() is now spec-correct out of the box. Emits "vcon": "0.4.0" automatically and no longer initializes empty group: [] / redacted: {} blocks. Older versions required manual fixups.

  • add_wtf_transcription_analysis() added β€” sibling to add_wtf_transcription_attachment() that places the WTF payload into analysis[] (the canonical location per the speckit) with type: "transcription", vendor, product, schema, encoding: "json", JSON-stringified body.

  • add_attachment(encoding="json", ...) now works. Earlier reports that JSON-bodied attachments were rejected are stale.

  • add_wtf_transcription_attachment() helper for the World Transcription Format payload. See WTF Transcription extension for placement guidance β€” the recommended location is analysis[] (use _analysis), not attachments[].

  • Spec-correct field names. Pre-0.9.1 code used appended and must_support; the current spec uses amended and critical (the latter typically appears as must_understand[] at the top level). The library now uses the new names. Stored vCons with old names remain parseable for compatibility; new code should use the spec-correct names.

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 current vCon specification including:

  • Conversation Management: Parties, dialogs, attachments, and analysis

  • Contact Information: Multiple contact methods (tel, email, SIP, DID)

  • Media Support: Audio, video, text, and image formats

  • Security: Digital signatures and content hashing

  • Extensibility: Extensions and must_understand (a.k.a. critical) fields

  • Location Data: Civic address information (GEOPRIV)

  • Event Tracking: Party history with join/drop/hold/mute events

  • 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

Privacy Compliance with Lawful Basis Extension

Transcription with WTF Extension

Complete Example with Extensions

Key Features

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

Enhanced Party Information

Extensions and Must-Support

Enhanced Dialog Support

Party History Events

Disposition Values for Incomplete Dialogs

Civic Address Support

Lawful Basis Extension (Privacy Compliance)

WTF Extension (Transcription Support)

Provider Data Conversion

Installation

Basic Usage

Creating a vCon

Loading a vCon

Validation

Media Support

Audio and Video

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

Content Hashing

Advanced Features

Property Handling

Transfer Dialogs

Analysis Data

Specification Compliance

This library implements the latest vCon specification with:

  • βœ… All required fields and validation

  • βœ… Proper media type support

  • βœ… Civic address (GEOPRIV) compliance

  • βœ… Party history event tracking

  • βœ… Transfer dialog support

  • βœ… Content hashing and security

  • βœ… Extensions and must_support

  • βœ… Flexible versioning (version field is optional)

  • βœ… 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:

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

Remaining quirks (0.9.4)

The library is broadly spec-compliant as of 0.9.4. Most historical quirks (manual syntax-param setting, empty group/redacted placeholders, add_attachment rejecting JSON, add_tag missing indices) were fixed across 0.9.2 and 0.9.3. Two edges still need attention:

  1. subject has no setter. Write via the dict:

  2. Lawful Basis: easier to build by hand. add_lawful_basis_attachment() requires model objects for purpose_grants and proof_mechanisms. Building the attachment dict directly per draft-howe-vcon-lawful-basis and appending to vcon_dict["attachments"] is usually simpler β€” then call v.add_extension("lawful_basis"). See Lawful Basis extension.

If you're scaffolding a new adapter, the vcon-adapter-template repo wraps both of these (and the syntax-param default for older library versions) in a single new_vcon() helper. See the adapter Quick Start.

Field-name migration (pre-0.9.1 β†’ 0.9.2)

If you're upgrading from pre-0.9.1 code or working with vCons produced by older libraries, you'll encounter two renamed fields:

Old name
New name
Where

appended

amended

Top-level vCon, mutually exclusive with redacted / group

must_support

critical (or must_understand)

Inside extensions[] declarations

The library reads both forms but writes the new ones. If you have downstream tooling that depends on the old names, update it; both vcon-mcp (database migration 20251120150100_field_renames.sql) and vcon-server have already moved.

Documentation

  • API Reference - Complete API documentation

  • User Guide - Comprehensive usage guide

  • LLM Guide - Guide for AI-assisted development

  • Migration Guide - Upgrading from older versions

License

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

Last updated

Was this helpful?