StegoFLAC

A focused toolkit for hiding, recovering, and analyzing encrypted data in FLAC audio.

---

Quick Links

• Quick Start
• What is StegoFLAC?
• Feature Overview
• Build a Standalone Binary
• Advanced Command Line Interface
• Detection Methods Overview
• High Performance Computing
• System Architecture
• Supported Capabilities
• Security and Preservation
• Legal Disclaimer and Contributing
• Copyright

---

Quick Start

Download a Release Binary

Download the build for your OS from the Releases page, unzip it, and run stegoflac from the extracted folder.

• No pip install required.
• No Python project checkout required.
• No PATH setup required.
• Run stegoflac by itself for the guided terminal menu.
• Run stegoflac encode, stegoflac decode, and other subcommands for direct automation.

Quick Launch from Source

Use the source install when you want to run tests, change the code, or work from the Python modules directly.

git clone https://github.com/slategraydev/StegoFLAC.git
cd StegoFLAC
pip install -r requirements.txt
pip install -e .

Run the test suite after installation.

python -m pytest

Generate a tiny deterministic FLAC fixture for local testing.

python tests/generate_fixtures.py

Launch the local dashboard.

stegoflac web --host 127.0.0.1 --port 5000

Interactive Terminal Menu

Run stegoflac with no subcommand to open the guided terminal menu.

stegoflac

The Rich terminal menu opens with a StegoFLAC banner, arrow-key selection, typed command shortcuts, guided prompts, status spinners, and result panels for encode, decode, detect, capacity, benchmark, and acceleration reports. Press Enter on the Quit row to leave immediately, or use the direct commands below when scripting.

Set STEGOFLAC_FAST_UI=1 to skip startup animation when you want the menu to open immediately.

Core Commands

# 1. Hide a file inside a FLAC carrier.
stegoflac encode -c carrier.flac -p secret.txt -o carrier.stego.flac -k "my-pass"

# 2. Recover the payload.
stegoflac decode -f carrier.stego.flac -o recovered.txt -k "my-pass"

# 3. Estimate usable payload capacity.
stegoflac capacity -c carrier.flac --depth 1

# 4. Inspect deterministic FLAC steganalysis features.
stegoflac detect -f carrier.stego.flac

# 5. Benchmark the vectorized hot path.
stegoflac bench --samples 1000000 --payload-bytes 4096

# 6. Compare tiled block sizes.
stegoflac bench-sweep --samples 1000000 --payload-bytes 4096

# 7. Measure thread overhead before trusting parallel chunks.
stegoflac bench-parallel --samples 1000000 --block-samples 65536 --workers 4

# 8. Launch the local web dashboard.
stegoflac web --host 127.0.0.1 --port 5000

Use STEGOFLAC_KEY to keep the passphrase out of shell history.

export STEGOFLAC_KEY="my-pass"
stegoflac decode -f carrier.stego.flac -o recovered.txt

---

What is StegoFLAC?

Simple Version: StegoFLAC hides an encrypted payload in the low bit planes of lossless FLAC PCM samples. The output is still a FLAC file, and the payload can be recovered with the same key, depth, and decoding path.

StegoFLAC is a FLAC steganography toolkit for controlled audio payload embedding, extraction, detection, and benchmarking. It combines AES-256-GCM payload protection, Argon2id passphrase derivation, NumPy-backed sample mutation, deterministic FLAC anomaly reporting, a Typer CLI, and a local Flask dashboard.

The expected workflow is FLAC in, FLAC out, with PCM sample values preserved between embedding and extraction. That makes the behavior easy to test, benchmark, and reason about.

$ stegoflac encode --carrier carrier.flac --payload secret.txt --output carrier.stego.flac --key "my-pass"
+ embedded payload into carrier.stego.flac

$ stegoflac detect --file carrier.stego.flac
{
  "lsb_one_ratio": 0.5001,
  "suspicion": "medium",
  "high_risk_windows": [...],
  "entropy": {...},
  "correlation": {...}
}

---

Feature Overview

Area	What It Covers	Useful Details
FLAC carriers	.flac input and output with PCM_16 and PCM_24 support.	Validates container metadata and sample subtype before processing.
Sample embedding	Low-bit-plane payload storage.	Uses 1 to 4 stored bit planes per sample, with capacity checks before writes.
Payload framing	Recoverable encrypted payload packets.	Stores an outer length prefix plus filename and payload frame data.
Cryptography	AES-256-GCM and Argon2id protection.	Generates fresh salt and nonce values per payload.
Detection	Deterministic FLAC anomaly reporting.	Reports bit-plane ratios, window scores, run lengths, residuals, entropy, and correlation features.
High Performance Computing	CPU and NumPy-focused acceleration paths.	Includes vectorized bit packing, tiled kernels, chunk planning, packing helpers, and benchmark commands.
Interfaces	Guided terminal menu, direct CLI, and local Flask dashboard.	Supports encode, decode, detect, capacity, bench, bench-sweep, bench-parallel, accel, and web workflows.

---

Build a Standalone Binary

Standalone CLI folders are built with PyInstaller through the Build Standalone Binaries GitHub Actions workflow. Tagged builds are zipped and attached to the GitHub Releases page. These are self-contained terminal bundles, not polished OS installers. Running stegoflac opens the Rich guided menu, and running a subcommand keeps the direct CLI behavior.

Build one locally from the project root.

python -m pip install -e ".[binary]"
pyinstaller --clean --noconfirm stegoflac.spec

Smoke-check the generated executable.

./dist/stegoflac/stegoflac --version

On Windows, use:

.\dist\stegoflac\stegoflac.exe --version

The PyInstaller spec includes the CLI entry point, Flask templates and static files, and soundfile package data. If a local executable reports missing soundfile/libsndfile, install libsndfile for that platform and rebuild. See packaging/README.md for the quieter version of that headache.

---

Advanced Command Line Interface

StegoFLAC supports both a guided terminal menu and direct commands. Each subcommand maps to one FLAC workflow, from embedding and extraction to detection, capacity checks, and benchmarks.

1. Payload Encoding

# Basic encrypted payload embedding.
stegoflac encode -c carrier.flac -p secret.txt -o carrier.stego.flac -k "passphrase"

# Use 2 low bits per sample for more capacity with more signal disturbance.
stegoflac encode -c carrier.flac -p model.bin -o model.stego.flac -k "passphrase" --depth 2

2. Payload Decoding

# Decode with the same key and depth used for embedding.
stegoflac decode -f model.stego.flac -o model.out -k "passphrase" --depth 2

# Decode with STEGOFLAC_KEY instead of a command-line key.
export STEGOFLAC_KEY="passphrase"
stegoflac decode -f carrier.stego.flac -o recovered.txt

3. Deterministic FLAC Detection

# Print FLAC anomaly features as JSON.
stegoflac detect -f carrier.stego.flac

The detector is deterministic. It reports statistical features for triage, regression checks, and suspicious-file review.

4. Capacity and Benchmarks

# Estimate payload room at a chosen bit depth.
stegoflac capacity -c carrier.flac --depth 1

# Print runtime acceleration information.
stegoflac accel

# Run a larger synthetic vector benchmark with the default NumPy backend.
stegoflac bench --samples 8000000 --depth 2 --payload-bytes 65536

# Run the tiled backend with padded tails for uniform block work.
stegoflac bench --backend tiled --block-samples 65536 --pad-tail

# Compare cache-block tile sizes.
stegoflac bench-sweep --samples 1000000 --payload-bytes 4096

# Measure thread overhead on chunked LSB scans.
stegoflac bench-parallel --samples 1000000 --block-samples 65536 --workers 4

5. Local Web Dashboard

stegoflac web --host 127.0.0.1 --port 5000

The web dashboard is local Flask. It wraps the same encode, decode, detect, and benchmark workflows in a browser interface.

---

Detection Methods Overview

Method	Target Data	What It Reports
Bit-plane ratios	FLAC PCM samples	One-ratio summaries for the embedded plane and nearby low planes.
Chi-square score	LSB plane	Whole-file balance score for low-plane distribution checks.
Block ratios	LSB windows	Per-block LSB one-ratios for local anomaly triage.
Sliding chi-square	LSB windows	Windowed balance scores, useful for spotting localized embedding.
Run lengths	Low bit planes	Run count, mean, median, maximum, and single-bit run ratio.
Autocorrelation	LSB sequence	Neighbor-to-neighbor LSB correlation across the flattened PCM stream.
Channel correlation	Stereo or multi-channel PCM	Pairwise low-plane correlation between channels.
Residual LSB stats	Sample differences	LSB ratio, chi-square, entropy, and RMS after frame differencing.
Entropy summary	LSB windows	Whole-file and per-window entropy summaries.
High-risk windows	Ranked windows	The highest-scoring windows with short reasons for the score.

---

High Performance Computing

StegoFLAC spends its optimization budget on the encode and decode path, where FLAC samples are unpacked, modified, packed, and verified. That work is mostly array masking and buffer movement, so the supported fast path is CPU plus NumPy, measured with benchmark commands instead of guesses.

Technique	Status	What It Means
NumPy vectorized bit packing	Supported	Converts payload bytes to bit arrays without Python loops.
Masked PCM writes	Supported	Applies bit-plane changes over contiguous sample arrays.
Chunk planning	Supported	Splits large files into deterministic ranges, including keyed order for embed and extract.
Cache-block sweep	Supported	Tests several sample tile sizes so the fast path is measured on the current machine.
Tiled bit-plane kernel	Supported	Processes fixed-size PCM tiles with fewer small array operations.
Tail padding benchmark	Supported	Compares explicit tail handling with padded uniform tiles.
Parallel overhead benchmark	Supported	Measures when chunk workers help and when scheduling overhead costs more than it saves.
Acceleration probe	Supported	Reports CPU count, NumPy version, and visible SIMD features for the current runtime.

The supported benchmark commands are bench, bench-sweep, and bench-parallel. They measure tile size, contiguous PCM packing, padded tails, and worker overhead, because those are the parts most likely to decide whether a FLAC job is fast or just loud about being fast.

---

System Architecture

StegoFLAC/
├── .github/workflows/
│   ├── ci.yml                 # Windows, macOS, and Linux test matrix
│   └── build-binaries.yml     # PyInstaller release artifact workflow
├── README.md
├── pyproject.toml             # Package metadata, dependencies, and CLI entry point
├── requirements.txt           # Runtime and test dependency list
├── stegoflac.py               # Typer command line entry point
├── stegoflac.spec             # PyInstaller standalone CLI configuration
├── core/
│   ├── base.py                # Shared project primitives
│   ├── version.py             # Version metadata
│   ├── crypto/aes.py          # Argon2id and AES-256-GCM packet protection
│   ├── flac/                  # I/O, framing, LSB engine, chunks, capacity
│   └── hpc/                   # Acceleration probes, benchmarks, packing, SIMD, Numba hook
├── detect/flac_anomaly.py     # FLAC bit-plane, residual, entropy, and correlation summaries
├── protocol/manifest.py       # Workflow manifest helpers
├── web/                       # Flask dashboard, static assets, and templates
├── tui/                       # Rich terminal menu, theme, and render helpers
├── packaging/README.md        # Standalone binary build notes
├── tests/                     # CLI, crypto, detector, FLAC LSB, and performance tests
│   └── fixtures/              # Small generated fixture location
└── tasks/todo.md              # Project planning notes

---

Supported Capabilities

Carrier Format	Injection Method	Extraction Status	Deterministic Detection	Benchmark
FLAC PCM_16	✅ LSB, 1 to 4 bits per sample	✅ Supported	✅ Supported	✅ Supported
FLAC PCM_24	✅ Shift-aware low stored bit planes	✅ Supported	✅ Supported	✅ Supported

The supported FLAC path covers encrypted payload framing, sample-level embedding, deterministic detection, capacity estimation, and synthetic performance benchmarks.

---

Security and Preservation

Payloads are encrypted with AES-256-GCM. Keys are derived from a passphrase with Argon2id. The detector reports explainable statistical features for triage, regression checks, and suspicious-file review.

The expected preservation path is FLAC to FLAC with PCM sample values intact. Keep the same bit depth for decode that you used for encode, and keep the passphrase available through --key or STEGOFLAC_KEY.

---

Legal Disclaimer and Contributing

Strictly Educational Disclaimer: StegoFLAC is for research, education, defensive testing, CTF work, and lawful data-hiding experiments. Unauthorized exfiltration, evasion, harassment, and illegal content concealment are outside lawful use. The author accepts no liability for misuse.

Contributing: Pull requests should strengthen the FLAC encode, decode, detection, capacity, benchmark, or dashboard workflows. New behavior should include tests and should keep public README claims tied to implemented code.

---

Copyright

Copyright (c) 2026 Randall Rosas (Slategray). All rights reserved.