AudioKey is a Python-first system that derives AES keys from audio features, evaluates segment quality with an agent (and optional CNN model), and exposes both CLI and FastAPI interfaces with a React frontend.
- Python 3.9+
- Audio processing:
librosa,numpy,scipy,pydub,soundfile - Cryptography:
pycryptodome(AES-256-CBC) - ML:
torch,torchvision(AudioKeyCNN) - Backend API:
FastAPI,uvicorn,pydantic - Frontend:
React 18+Vite - Testing:
pytest(plus direct component test script)
pip install -r requirements.txtpython tests/test_components.pypython app/cli.py agent-infopython app/cli.py generate-key path/to/audio.wavOptional flags:
python app/cli.py generate-key path/to/audio.wav --pin "1234"
python app/cli.py generate-key path/to/audio.wav --no-evaluate
python app/cli.py generate-key path/to/audio.wav --save-processed --processed-dir data/processeduvicorn app.api:app --reload --port 8000cd frontend
npm install
npm run devFrontend runs on http://localhost:5173 and calls backend on http://localhost:8000.
# Generate key
python app/cli.py generate-key <audio_file> [--pin PIN] [--no-evaluate]
# Encrypt text
python app/cli.py encrypt-text "hello" <key_hex>
# Decrypt text
python app/cli.py decrypt-text <ciphertext_hex> <iv_hex> <key_hex>
# Agent info
python app/cli.py agent-infoAudioKey is built to make encryption key generation more practical and user-driven by deriving keys from audio content instead of manually managed passwords or key files.
Primary goals:
- Derive deterministic 256-bit keys from audio features.
- Evaluate whether a segment is suitable for key generation before use.
- Provide both CLI and web-based workflows for real usage.
- Keep generated key operations auditable with local key-vault and usage logs.
- Personal secure notes or file snippets where users prefer audio-based keying material.
- Classroom/lab demonstrations of AI + cybersecurity integration.
- Prototyping adaptive key selection pipelines using audio quality signals.
- Local-first secure tooling where keys are not hardcoded in scripts.
- Research baselines for comparing rule-based vs model-assisted key quality assessment.
AudioKey includes an agentic quality-evaluation loop that runs before final key selection.
How it works:
- The input audio is normalized, segmented, and converted to spectrogram/features.
- Each segment is evaluated by the agent using expert rules and optional
AudioKeyCNNinference. - The workflow compares segment reports and selects the best candidate.
- A final decision package is produced, including quality, confidence, risk factors, and recommendations.
- Key derivation runs on the selected segment.
What you see in practice:
- CLI:
python app/cli.py generate-key <audio_file>prints quality results, risk factors, and recommendations before key output. - CLI (with trace): running generation with evaluation shows agent trace entries for decision stages.
- Backend workflow: the same agentic pipeline is used by the FastAPI service, including asynchronous job progression and decision metadata.
Why it matters:
- Reduces weak-segment key generation.
- Gives explainability (decision + confidence + risks) instead of opaque key output.
- Supports fallback behavior: if no pretrained model is available, rule-based evaluation still works.
Train the CNN model (synthetic dataset pipeline in current implementation):
python models/train.pyThe trained weights are saved to models/audkeycnn_pretrained.pt.
agent/ Agentic quality evaluation workflow
app/ CLI and FastAPI app
core/ Audio processing, key derivation, AES crypto
models/ AudioKeyCNN model and training script
frontend/ React + Vite client
tests/ Component-level tests
data/ Processed artifacts, key vault, logs
docs/ Setup and project documentation
- If
models/audkeycnn_pretrained.ptis missing, CLI/API still works with rule-based evaluation. - Generated key vault and usage logs are stored in
data/processed/.