dhvagna 0.1.3
A streamlined audio transcription package requiring minimal code with outperformed accuracy.
Requires Python: >=3.8
Keywords: audio, transcription, speech recognition, voice-to-text, telugu, whisper

# Dhvagna

A streamlined Python package for audio-to-text transcription that requires only 4-7 lines of code to implement powerful voice transcription features. Dhvagna supports multiple languages including Telugu and English with customizable prompts.

[![PyPI version](https://badge.fury.io/py/dhvagna.svg)](https://badge.fury.io/py/dhvagna)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Minimal Code**: Transcribe audio in just 4-7 lines of code
- **Multiple Languages**: Built-in support for Telugu, English, and many other languages
- **Customizable Prompts**: Improve transcription accuracy with domain-specific prompts
- **Flexible Input**: Process audio from files, URLs, or in-memory bytes
- **Detailed Output**: Get timestamps for each segment of speech
- **Batch Processing**: Easily transcribe multiple files
- **Extensible Tools**: Create custom tools for pre/post-processing
- **PyTorch Integration**: Uses state-of-the-art Whisper models from OpenAI

## Installation

```bash
pip install dhvagna==0.1.3
```

## Quick Start

Transcribe an audio file in just 4 lines:

```python
from dhvagna import audio_to_text

audio_path = "path/to/your/audio.wav"
transcript = audio_to_text(audio_path)
print(transcript)
```

## Cookbook

### 1. Basic Transcription

```python
from dhvagna import audio_to_text

# Transcribe audio with just 4 lines of code
audio_path = "path/to/your/audio/file.wav"
transcript = audio_to_text(audio_path)
print(transcript)
```

### 2. Telugu Language Transcription

```python
from dhvagna import audio_to_text

# Transcribe Telugu audio
audio_path = "path/to/your/telugu_audio.wav"
transcript = audio_to_text(
    audio_path,
    language="te",  # Telugu language code
    model_size="medium"  # Using medium model for better accuracy
)
print(transcript)
```

### 3. Custom Prompts for Better Accuracy

```python
from dhvagna import Transcriber

# Initialize transcriber with a custom prompt
transcriber = Transcriber(
    model_size="small",
    prompt="This is a technical discussion about Python programming"
)

# Transcribe audio file
audio_path = "path/to/your/technical_discussion.wav"
transcript = transcriber.transcribe_file(audio_path)
print(transcript)
```

### 4. Processing Audio from Memory (URLs/Bytes)

```python
import requests
from dhvagna import audio_to_text

# Download audio file from URL directly into memory
audio_url = "https://example.com/sample-audio.wav"
response = requests.get(audio_url)
audio_bytes = response.content

# Transcribe audio bytes
transcript = audio_to_text(
    audio_bytes, 
    model_size="small",
    language="en"
)
print(transcript)
```

### 5. Batch Processing Multiple Files

```python
import os
from dhvagna import Transcriber

def batch_transcribe(audio_dir, output_dir, language=None):
    # Create output directory if it doesn't exist
    os.makedirs(output_dir, exist_ok=True)
    
    # Initialize transcriber
    transcriber = Transcriber(model_size="base", language=language)
    
    # Process all audio files in the directory
    for filename in os.listdir(audio_dir):
        if filename.endswith(('.wav', '.mp3', '.flac', '.ogg')):
            # Input and output paths
            audio_path = os.path.join(audio_dir, filename)
            output_path = os.path.join(output_dir, f"{os.path.splitext(filename)[0]}.txt")
            
            # Transcribe and save
            print(f"Transcribing {filename}...")
            transcriber.transcribe_file(audio_path, output_path=output_path)
            print(f"Saved to {output_path}")

# Just 5 lines of code to process an entire directory of files
audio_directory = "path/to/audio/files"
output_directory = "path/to/save/transcripts"
batch_transcribe(audio_directory, output_directory, language="en")
```

### 6. Getting Transcription with Timestamps

```python
from dhvagna import audio_to_text
import json

# Transcribe audio with timestamps
audio_path = "path/to/your/audio/file.wav"
result = audio_to_text(
    audio_path,
    return_segments=True  # Get detailed segments with timestamps
)

# Process the detailed result
print(f"Full transcript: {result['text']}\n")
print("Segments with timestamps:")
for segment in result["segments"]:
    start_time = segment["start"]
    end_time = segment["end"]
    segment_text = segment["text"]
    print(f"[{start_time:.2f}s - {end_time:.2f}s]: {segment_text}")
```

### 7. Creating Custom Tools for Processing

```python
from dhvagna import ToolsFactory, audio_to_text

# Create a tools factory
factory = ToolsFactory()

# Define a post-processor function to clean up transcription
def clean_transcript(text, remove_filler_words=True):
    """Clean up transcript by removing filler words and normalizing text."""
    if remove_filler_words:
        filler_words = ["um", "uh", "like", "you know", "actually"]
        for word in filler_words:
            text = text.replace(f" {word} ", " ")
    
    # Normalize multiple spaces
    import re
    text = re.sub(r'\s+', ' ', text).strip()
    return text

# Create a tool that applies the post-processor
factory.create_tool(
    name="transcript_cleaner",
    description="Cleans transcription by removing filler words",
    post_processor=clean_transcript,
    params={"remove_filler_words": True}
)

# Function to transcribe audio (to be used with the tool)
def transcribe_audio(audio_path):
    return audio_to_text(audio_path)

# Use the tool on an audio file
audio_path = "path/to/your/audio.wav"
clean_transcript = factory.use_tool(
    name="transcript_cleaner",
    audio_source=audio_path,
    transcriber_func=transcribe_audio
)

print(clean_transcript)
```

## Available Functions

### Core Functions

- `audio_to_text(audio_source, model_size="base", language=None, prompt=None, output_path=None, return_segments=False, **kwargs)` - Main utility function for transcription in 4-7 lines
- `load_audio(file_path)` - Load audio file as bytes
- `save_transcript(text, output_path)` - Save transcription text to a file

### Transcriber Class

- `Transcriber(model_size="base", language=None, prompt=None, device=None)` - Main transcription class
  - `transcribe_file(audio_path, output_path=None, return_segments=False, **kwargs)` - Transcribe audio file
  - `transcribe_bytes(audio_bytes, output_path=None, return_segments=False, **kwargs)` - Transcribe audio bytes
  - `get_available_languages()` - Get list of supported languages
  - `get_prompt()` - Get current prompt
  - `set_prompt(prompt)` - Set custom prompt

### ToolsFactory Class

- `ToolsFactory(tools_dir=None)` - Factory for creating custom processing tools
  - `create_tool(name, description, pre_processor=None, post_processor=None, params=None)` - Create new tool
  - `get_tool(name)` - Get tool by name
  - `list_tools()` - List all available tools
  - `delete_tool(name)` - Delete a tool
  - `use_tool(name, audio_source, transcriber_func, **kwargs)` - Use a tool for processing

## Model Sizes

Dhvagna supports different Whisper model sizes:

- `tiny`: Fastest, lowest accuracy (good for testing)
- `base`: Good balance of speed and accuracy for general use
- `small`: Better accuracy than base, slightly slower
- `medium`: High accuracy, slower processing
- `large`: Best accuracy, slowest processing

## Supported Languages

Dhvagna supports all languages supported by Whisper, including:

- Telugu (`te`)
- English (`en`)
- Hindi (`hi`)
- Tamil (`ta`)
- And many more...

## License

MIT License - see the LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.