wavcore 1.0.2

Ultra-fast lossless voice codec — real-time recording, VTXT text serialization, and bit-perfect reconstruction with a C engine.

WavCore

Ultra-fast, lossless real-time voice codec powered by a C engine

WavCore is a Python package for recording, serializing, transmitting, and reconstructing voice audio with bit-perfect precision.

It converts microphone audio into a human-readable text format called VTXT (.vtxt), making voice easy to store, sync, inspect, and send through text-friendly systems without requiring a heavy binary streaming server.

Created by Prashant Pandey
Repository: https://github.com/Zyro-Hub/wavecore

---

What WavCore Does

WavCore captures microphone audio, splits it into small frames, converts each frame into hexadecimal text, and stores it as a .vtxt file.

That means you can:

• record voice locally
• send voice over HTTP, Firebase, databases, or chat systems
• reconstruct the original audio later
• verify every frame with CRC-32 integrity checks

WavCore is designed for:

• real-time voice communication
• voice messaging apps
• lightweight transport systems
• IoT and edge devices
• research, debugging, and forensic audio work

---

Key Features

• Lossless audio encoding
  Preserves float32 audio samples exactly using IEEE-754 hex encoding.

• C engine for speed
  Core conversion and CRC operations are accelerated with a compiled C backend.

• Frame-based design
  Audio is processed in small frames for low-latency communication.

• CRC-32 integrity checks
  Each frame can be verified for corruption, missing data, or transmission issues.

• Human-readable VTXT format
  Audio becomes plain text, easy to inspect, diff, store, and send.

• Gap handling
  Missing frames can be replaced with silence during reconstruction.

• Pure-Python fallback
  Works even if native compilation is unavailable.

• Lightweight server requirement
  Because VTXT is text, it can work with simple transport layers such as Firebase Realtime Database for many real-time voice communication use cases, without requiring a powerful custom streaming server.

---

Installation

pip install wavcore

Dependencies

WavCore installs its core dependencies automatically:

• numpy
• sounddevice
• cffi

The C engine is compiled during installation when native build support is available.

---

Quick Start

import wavcore

# Record 10 seconds of voice into VTXT
wavcore.record("audio.vtxt", "original.wav", duration=10)

# Reconstruct the audio and play it back
wavcore.decode("audio.vtxt", "reconstructed.wav", play=True)

# Check which engine is active
print(wavcore.engine_info())

Example output:

C engine [cffi / MSVC 64-bit] — ultra-fast

---

Why VTXT?

VTXT is WavCore’s voice text format.

Instead of storing voice as binary audio data, WavCore stores it as readable text, frame by frame.

Benefits

• easy to transmit through text-based systems
• simple to store in databases
• easy to debug and inspect
• works well with APIs and realtime sync systems
• fully round-trippable back to audio

Example

[FILE_HEADER]
SAMPLE_RATE=48000
TOTAL_FRAMES=500
DURATION_MS=10000.000000
[/FILE_HEADER]

[FRAME]
FRAME_ID=0
TIMESTAMP_MS=1745123456789.000000
ORIG_CRC32=BC5C582D
SAMPLES_HEX=3C8B43963D...
[/FRAME]

---

Main Use Cases

1. Real-Time Voice Messaging

WavCore is useful when you want voice to move like text.

You can:

• record voice
• encode it into .vtxt
• send it to another device
• decode and play it back

This is useful for voice chat, voice notes, and custom communication apps.

---

2. Firebase Realtime Voice Communication

Because .vtxt is text, WavCore can work with Firebase Realtime Database as a simple transport layer.

That means:

• no need for a heavy media server
• no need for binary stream handling
• no need for complex codec pipelines

A voice message can be:

• recorded locally
• encoded into .vtxt
• written to Firebase
• read on another device
• decoded back into audio

This makes WavCore a strong choice for lightweight realtime voice systems.

---

3. IoT and Edge Devices

Text transport is often easier for small devices and constrained environments.

WavCore can help when devices need to send voice data through a lightweight backend or a simple sync channel.

---

4. Research and Debugging

Because the format is readable, you can inspect frame data, integrity values, and transmission issues directly.

---

API Reference

High-Level Functions

Function	Description
wavcore.record(vtxt_path, orig_wav, duration, sample_rate, frame_ms)	Record microphone audio and save .vtxt plus reference WAV
wavcore.decode(vtxt_path, output_wav, play)	Decode .vtxt into reconstructed WAV and optionally play it
wavcore.engine_info()	Show the active engine and performance tier

Low-Level Functions

Function	Description
wavcore.batch_encode(audio, spf)	Convert float32 audio into a list of hex strings
wavcore.batch_decode(hex_list, spf)	Convert hex strings back into float32 audio
wavcore.compute_frame_crc(...)	Compute frame CRC-32 for integrity checks

---

Performance

WavCore is designed for frame-based real-time use.

Typical benchmark results:

Operation	Frames	Time
Encode	500	~7.5 ms
Decode	500	~4.6 ms
CRC verify	500	~7.4 ms
Full pipeline	500	~35.8 ms

A 20 ms frame at 48 kHz gives a budget of 20,000 µs per frame.
WavCore uses only a tiny fraction of that budget.

---

Architecture Overview

Microphone input
   ↓
float32 audio samples
   ↓
C batch encoder
   ↓
CRC-32 per frame
   ↓
VTXT text file
   ↓
transport / storage
   ↓
C batch decoder
   ↓
WAV reconstruction
   ↓
speaker playback

---

Example: Send Voice as Text

import wavcore
import requests

# Sender
wavcore.record("message.vtxt", "original.wav", duration=5)

with open("message.vtxt", "r", encoding="utf-8") as f:
    payload = f.read()

requests.post(
    "https://your-api.com/voice",
    data=payload.encode("utf-8"),
    headers={"Content-Type": "text/plain; charset=utf-8"},
)

# Receiver
response = requests.get("https://your-api.com/voice/latest")

with open("received.vtxt", "w", encoding="utf-8") as f:
    f.write(response.text)

wavcore.decode("received.vtxt", "playback.wav", play=True)

---

Example: Firebase Realtime Database Flow

import wavcore
import firebase_admin
from firebase_admin import credentials, db

# Record voice
wavcore.record("voice.vtxt", "voice.wav", duration=5)

# Load VTXT text
with open("voice.vtxt", "r", encoding="utf-8") as f:
    vtxt_data = f.read()

# Push to Firebase
ref = db.reference("voice_messages")
ref.push({
    "sender": "Prashant Pandey",
    "vtxt": vtxt_data,
    "created_at": "2026-04-21T00:00:00Z"
})

# Read and decode on another device
messages = ref.get()

This pattern is especially useful when you want simple real-time text sync instead of a dedicated media server.

---

Output Files

WavCore can generate:

• .vtxt — the main serialized voice format
• .wav — original recorded reference
• .wav — reconstructed playback audio

---

Documentation

See the docs/ folder for more detailed documentation, architecture notes, and implementation details.

---

Notes

WavCore is optimized for:

• lossless round-trip audio preservation
• text-friendly transport
• low-latency frame processing
• simple integration in messaging and sync systems

It is a voice codec and serialization system, not a lossy compression codec.

---

Developer

Prashant Pandey

Email:

• [e-mail]
• [e-mail]

GitHub:

https://github.com/Zyro-Hub/wavecore

---

License

MIT License

---

Project Summary

WavCore turns voice into text, keeps it verifiable, and reconstructs it back into audio with high precision.

It is built for developers who want:

• fast voice transport
• readable audio serialization
• real-time frame processing
• simple integration with text-based backends

---