Metadata-Version: 2.4
Name: wavcore
Version: 1.0.2
Summary: Ultra-fast lossless voice codec — real-time recording, VTXT text serialization, and bit-perfect reconstruction with a C engine.
License-Expression: MIT
Project-URL: Homepage, https://github.com/Zyro-Hub/wavecore
Project-URL: Source, https://github.com/Zyro-Hub/wavecore
Project-URL: Issues, https://github.com/Zyro-Hub/wavecore/issues
Keywords: audio,codec,voice,recording,lossless,real-time
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21.0
Requires-Dist: sounddevice>=0.4.5
Requires-Dist: cffi>=1.15.0
Provides-Extra: dev
Requires-Dist: matplotlib>=3.5.0; extra == "dev"
Requires-Dist: scipy>=1.7.0; extra == "dev"

# 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

```bash
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

```python
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:

```text
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

```text
[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

```text
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

```python
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

```python
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:

- technical121@gmail.com
- codex.admim@gmail.com

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

---
