speakline 0.1.0

Record voice and insert as inline code comments across any language and IDE

VoiceComment

Record voice and insert as inline code comments across any language and IDE.

Turn your spoken thoughts into well-formatted code comments with a single command. Works with Python, JavaScript, TypeScript, Go, Rust, Java, and more.

Features

• Voice Recording: Local microphone input with silence detection
• Transcription: Support for Whisper (local) and OpenAI API
• Smart Comment Insertion: Language-aware parser with proper indentation
• Multi-Language Support: Python, JavaScript, TypeScript, Go, Rust, Java, C#, Ruby
• Pluggable Backends: Swap recorders, transcribers, and parsers easily
• Flexible API: CLI, Python package, and programmatic access
• Production-Ready: Type hints, error handling, and comprehensive logging

Installation

Prerequisites

• Python 3.9+
• PortAudio (for audio recording)

macOS

brew install portaudio

Ubuntu/Debian

sudo apt-get install portaudio19-dev

Windows

PortAudio is typically bundled. If not, download from PortAudio Downloads.

Install Package

pip install voicecomment

Or from source (development):

git clone https://github.com/yourusername/voicecomment
cd voicecomment
pip install -e .

Quick Start

Command Line

# Record and insert comment at line 42
voicecomment record myfile.py 42

# With fixed duration (5 seconds)
voicecomment record myfile.py 42 --duration 5

# Transcribe without modifying file
voicecomment transcribe

# Insert comment directly (no recording)
voicecomment insert myfile.py 42 "This is my comment"

Python API

from voicecomment import VoiceCommenter

# Auto-detect language from file extension
commenter = VoiceCommenter()
commenter.record_and_insert('myfile.py', line_number=42)

# Or specify language explicitly
commenter = VoiceCommenter(language='python')
commenter.record_and_insert('main.py', line_number=15)

# Transcribe only
text = commenter.transcribe_only()
print(text)  # "This function calculates factorial recursively"

# Insert into code string (no file I/O)
code = """
def factorial(n):
    return n * factorial(n - 1) if n > 1 else 1
"""
updated = commenter.insert_comment_to_string(
    code,
    "Base case for recursion",
    line_number=3
)
print(updated)

Jupyter Notebook

from voicecomment import VoiceCommenter

commenter = VoiceCommenter(language='python')

# Record and modify cell code
code_str = """
def process_data(df):
    return df.dropna()
"""

updated = commenter.insert_comment_to_string(
    code_str,
    "Remove rows with missing values",
    line_number=2
)
print(updated)

Architecture

Core Components

1. AudioRecorder (recorder.py)

• LocalAudioRecorder: Captures audio from system microphone
• Supports fixed duration or silence detection
• Configurable sample rate, channels, and format

2. Transcriber (transcriber.py)

Pluggable backends:

• WhisperTranscriber: Local OpenAI Whisper model (no API key needed)
• OpenAITranscriber: OpenAI Whisper API
• MockTranscriber: For testing without audio hardware

# Use local Whisper
from voicecomment.transcriber import WhisperTranscriber
transcriber = WhisperTranscriber(model_size="base")

# Or OpenAI API
from voicecomment.transcriber import OpenAITranscriber
transcriber = OpenAITranscriber(api_key="sk-...")

3. CodeParser (parser.py)

Language-specific parsers:

• PythonParser: Uses # prefix with proper indentation
• JavaScriptParser: Uses // prefix
• GenericParser: Configurable fallback for unsupported languages

4. VoiceCommenter (commenter.py)

Main orchestration class that ties everything together.

Advanced Usage

Custom Transcriber

from voicecomment import VoiceCommenter
from voicecomment.transcriber import TranscriberBase
import numpy as np

class CustomLLMTranscriber(TranscriberBase):
    def transcribe(self, audio: np.ndarray, sample_rate: int = 16000) -> str:
        # Your LLM logic here
        return "custom transcription"

commenter = VoiceCommenter(transcriber=CustomLLMTranscriber())
commenter.record_and_insert('file.py', line_number=10)

Custom Audio Config

from voicecomment import VoiceCommenter, AudioConfig

config = AudioConfig(
    sample_rate=44100,  # High-quality audio
    channels=2,         # Stereo
)

commenter = VoiceCommenter(audio_config=config)

Integration with IDE Extensions

The Python package can be called from:

• VS Code Extension: Via subprocess or Node.js child process
• Vim Plugin: Via Python 3 interface
• Neovim: Via Python plugin host
• Emacs: Via python-shell

Example VS Code extension (snippet):

const { spawn } = require('child_process');

const proc = spawn('voicecomment', ['record', filepath, lineNumber.toString()]);
proc.on('close', (code) => {
  if (code === 0) {
    vscode.window.showInformationMessage('Comment inserted!');
  }
});

Development

Setup

git clone https://github.com/yourusername/voicecomment
cd voicecomment
pip install -e ".[dev]"

Testing

pytest
pytest --cov  # With coverage

Code Quality

black .
ruff check .
mypy voicecomment/

Supported Languages

Language	Extension	Comment Prefix
Python	.py, .pyw	#
JavaScript	.js, .jsx, .mjs	//
TypeScript	.ts, .tsx, .mts	//
Go	.go	//
Rust	.rs	//
Java	.java	//
C#	.cs	//
Ruby	.rb	#
C/C++	.c, .cpp, .h, .hpp	//

Roadmap

• VS Code Extension (official)
• Vim/Neovim plugin
• Watch mode for automated comment markers
• Voice activity detection (VAD)
• Conversation-aware transcription (context from file)
• Custom prompt engineering for comment style
• Analytics dashboard (tracking comment patterns)
• LangChain integration for LLM-powered comments

Contributing

Contributions welcome! Please open an issue or pull request.

License

MIT License - see LICENSE

---

Built for developers who believe code comments should be as natural as talking.