Metadata-Version: 2.1
Name: ghostrate
Version: 1.0.4
Summary: Audio Steganography & Forensic Tool — Hide and reveal spoken messages in music
Home-page: https://ghostrate-xi.vercel.app
Author: Jawad Amin
License: MIT
Project-URL: Homepage, https://github.com/jawad/ghostrate
Keywords: audio,steganography,forensics,sound,dsp,encryption,watermark
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Security :: Cryptography
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# GhostRate

Audio steganography and forensic suite designed to embed hidden spoken voice messages inside any music track using phase mid-side inversion and phantom center balancing.

* **Normal Listening:** Plays as a completely standard stereo song on headphones, speakers, or car audio.
* **Filter-Immune:** Survives external audio converters, streaming compression, resamplers, and anti-aliasing downsampling.
* **Forensic Extraction:** Mid-side phase cancellation $(L - R)$ cancels the host music into silence, revealing the secret spoken voice with $+18\text{ dB}$ make-up gain.

## Web Studio

Access the interactive web studio directly in your browser:
**[https://ghostrate-xi.vercel.app](https://ghostrate-xi.vercel.app)**

Features real-time spectrogram visualizers, microphone recording, stealth gain adjustment, passcode protection, and a 1-click universal decoder.

## Installation

Install the offline CLI and Python module via pip:

```bash
pip install ghostrate
```

Zero third-party dependencies required. Uses only Python's standard library. Works on Python 3.8+ across Linux, macOS, and Windows.

## Quick Start & CLI Usage

Once installed, the `ghostrate` command is immediately available in your terminal:

### 1. Hide Voice Inside Music

```bash
# Standard stego track:
ghostrate hide music.wav voice.wav -o stego_song.wav --stealth 0.06

# Passcode-protected (scrambles speech using cryptographic sequence):
ghostrate hide music.wav voice.wav -o stego_song.wav --stealth 0.06 --key "MySecret123"
```

* `--stealth 0.06`: Adjusts voice stealth level (`0.03` for nearly invisible, `0.06` for balanced, `0.15` for louder).
* `--key "password"`: Scrambles the voice using a deterministic pseudo-random key sequence. Without this key, decoding yields only white noise.

### 2. Reveal Secret Message from Any Stego File

```bash
# Standard decoding:
ghostrate reveal stego_song.wav -o revealed_secret.wav

# Passcode-protected decoding:
ghostrate reveal stego_song.wav -o revealed_secret.wav --key "MySecret123"
```

Cancels out the host music and recovers the isolated speech.

### 3. Inspect Audio File Phase Correlation

```bash
ghostrate info stego_song.wav
```

Analyzes stereo difference energy to detect whether an audio track contains a hidden payload.

## How the Math Works

1. **Phantom Center Normalization:**  
   Most commercial songs have wide stereo guitars or synths ($L \ne R$). GhostRate first sums both channels into a phantom center mono base:
   $$M[n] = \frac{\text{Music}_L[n] + \text{Music}_R[n]}{2}$$

2. **Phase Inversion Embedding:**  
   $$\text{Left Ear} = M[n] + g \cdot \text{Voice}[n]$$
   $$\text{Right Ear} = M[n] - g \cdot \text{Voice}[n]$$

3. **Phase Cancellation Decoding:**  
   $$\text{Decoded} = \text{Left} - \text{Right} = (M - M) + 2g \cdot \text{Voice} = \mathbf{2g \cdot \text{Voice}}$$
   The music cancels to $0$, and the voice doubles in volume.

## Author

Developed by **Jawad Amin**.  
Web Studio: [https://ghostrate-xi.vercel.app](https://ghostrate-xi.vercel.app)

