# CryptoPhonic-音乐密码学美育平台

**Repository Path**: cloud-lumiere/CryptoPhonic

## Basic Information

- **Project Name**: CryptoPhonic-音乐密码学美育平台
- **Description**: 音乐×密码学：科学逻辑美学、数字艺术美学、创新创造美学的跨学科美育浸润
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CryptoPhonic · 音乐与密码学教育平台

一个面向密码科学与技术、信息安全专业大学新生的美育平台，通过**音乐**与**密码学**的交叉视角，帮助建立对信息安全核心概念的直觉理解。

**核心理念**：音乐与密码学在信息处理上遵循"编码 → 变换 → 传输 → 提取 → 解码"的**相同范式**。本项目构建了一套**音乐—密码学结构类比类比体系**，将信号载体、编码逻辑、隐藏机制、校验原理、变换规则五个维度一一对应，把抽象的密码学知识点转译为可交互的音乐视听实验。降低认知门槛，激发学习兴趣。

**技术约束**：纯原生 JavaScript（零依赖）、Web Audio API、Canvas 2D，浏览器打开即用。

---

## 项目结构

```
cryptophonic/
├── index.html              # 入口页面（沉浸式工作台壳：侧栏 + AppBar + 工作区）
├── README.md               # 项目文档
├── devlog.md               # 设计文档 & 开发日志
├── css/
│   └── style.css           # 设计令牌 + 布局壳 + 全部组件样式（浅色精致主题）
└── js/
    ├── fft.js              # 自实现 FFT（Cooley-Tukey 基-2 蝶形算法）
    ├── utils.js            # 工具函数（formatTime、PitchDetector、波形预计算）
    ├── audio-engine.js     # Web Audio API 引擎封装（信号发生器 + 音频文件）
    ├── visualizer.js       # 可视化渲染（波形图 + 频谱图 + 整体波形）
    ├── stego.js            # 音频隐写引擎（LSB / Echo / Phase Coding）
    ├── codebook.js         # 音乐密码本（交互式钢琴 + 字母↔音符对应 + 演奏）
    ├── hashing.js          # 音乐哈希（SHA-256 / 感知哈希 pHash / 频谱指纹匹配）
    ├── substitution.js     # 单表替代密码（音乐凯撒 / 仿射 + 频率分析破解）
    ├── vigen.js            # 维吉尼亚多表替代密码（重合指数 + 卡西斯基测试）
    ├── wizard.js           # StepWizard 四步向导组件（①概念→②观察→③实验→④洞察）
    └── app.js              # 主控制器、路由切换、路线图渲染、进度持久化、UI 绑定、主循环
```

## 界面架构（沉浸式工作台）

```
┌──────────────┬──────────────────────────────────────────────────┐
│ 侧边栏        │ AppBar：当前模块 + 全局音频播放状态                      │
│ · Logo        │ ┌────────────────────────────────────────────┐  │
│ · 学习路线     │ │ 引导条：本模块要回答的核心问题                       │  │
│ · 六大工作台   │ │ ① 概念 → ② 观察 → ③ 实验 → ④ 洞察（StepWizard） │  │
│ · 完成度打勾   │ └────────────────────────────────────────────┘  │
│ · 进度条/指南 │ · 工作台内容面板（输入 / 操作 / 观察分区）                │
│              │ · 「密码学对应」升华卡片（美育落点）                     │
└──────────────┴──────────────────────────────────────────────────┘
```

- **学习路线图首页**（默认落地页）：7 张课程卡（周次 / 概念标签 / 完成态），点击进入对应工作台
- **侧边栏导航**：六大模块 + 完成度 ✓，移动端抽屉式展开
- **步骤引导**（StepWizard）：全部 6 个工作台采用「概念 → 洞察」的引导流程；「音频可视化」「音频隐写术」为 **①概念 → ②观察&实验 → ③洞察** 三步，其余 4 个工作台为 ①概念 → ②观察 → ③实验 → ④洞察 四步
- **学习进度**：localStorage 持久化访问与完成状态，侧栏进度条 + 路线图完成态
- **首次使用引导**：首次打开弹 3 步使用指南遮罩，侧栏「使用指南」可随时重看
- **设计令牌**：CSS 变量统一颜色 / 圆角 / 阴影 / 间距，浅色精致主题，主色为**蓝色**（#2563eb）

## 使用方式

直接在浏览器打开 `index.html` 即可使用。

## 已实现模块

### 模块一：音频可视化

| 功能 | 说明 |
|------|------|
| **信号发生器** | 频率滑块 (30–2000 Hz)，四种波形（正弦/方波/锯齿/三角） |
| **音频文件播放** | 选择/拖入文件，完整播放控制（播放/暂停/停止/跳转） |
| **波形图（时域）** | Canvas 实时绘制 PCM 采样点 |
| **频谱图（频域）** | 自实现 FFT 功率谱 + 渐变填充 + 峰值标记 |
| **整体波形** | 文件整体包络预览，播放游标跟踪，点击跳转 |
| **音高检测** | 自相关法基频检测，显示 Hz 和音符名（如 A4） |
| **暂停可视化** | 暂停时从原始数据切片，波形/频谱仍保持显示 |

### 模块二：音频隐写术

支持三种隐写方法共 6 种配置，可在独立分页中操作：

| 方法 | 配置 | 容量 | 鲁棒性 | 原理 |
|------|------|------|--------|------|
| **LSB (1-bit)** | 每采样点替换最低 1 bit | 高 | 极低 | 直接修改 PCM 最低有效位 |
| **LSB (2-bit)** | 每采样点替换最低 2 bit | 更高 | 极低 | 同上，容量翻倍，噪声略增 |
| **LSB (4-bit)** | 每采样点替换最低 4 bit | 最高 | 极低 | 同上，容量再翻倍 |
| **Echo (50/120)** | 回声延迟 50/120 样本 | 中 | 低 | 在两个延迟值中编码 0/1 |
| **Echo (80/200)** | 回声延迟 80/200 样本 | 中 | 低 | 同上，不同延迟组合 |
| **Phase Coding** | FFT 帧低频相位置 0/π | 低 | 中 | 在 FFT 相位中嵌入比特 |

**协议细节**：
- 载荷格式：`[MAGIC(1B)][Flags(1B)][Length(2B)][Checksum(1B)][Payload(NB)]`
- **MAGIC**：魔术头标识，供解码端自动识别合法载荷
- **Flags**：标记加密与位乱序是否启用
- **Length + Checksum**：长度声明与校验和，保证提取完整性
- 可选 XOR 加密（密码派生 32 字节密钥）
- 位乱序保护（密码种子洗牌采样位置，仅 LSB 方法）
- Auto Detect：自动尝试全部方法 + 校验 MAGIC/Checksum

**UI 交互**：
- 编码面板：选择载体音频 → 选方法 → 输密码 → 输消息 → 生成可下载 WAV
- 解码面板：选择隐写音频 → 选方法（或 Auto Detect）→ 输密码 → 显示解码消息 + 编码方法

### 模块三：音乐密码本

用交互式钢琴实现最朴素的"码本"思想——字母 ↔ 音符的一一对应：

| 功能 | 说明 |
|------|------|
| **交互式钢琴** | C4–B6 三个八度，21 白键 + 15 黑键，点击发声试听 |
| **码本对应** | A–U → 21 个白键，V–Z → 5 个黑键，反向可查 |
| **琴键标注** | 每键显示音名 / 唱名（do re mi…）/ 字母（明文） |
| **显示选项** | 复选框自由切换琴键上显示：音名 / 唱名 / 字母 |
| **双向联动** | 点击琴键 → 映射表对应字母高亮；点击字母 → 对应琴键发声并高亮 |
| **音阶演示** | C 大调 / a 自然小调 / C 宫五声 / 半音阶，选曲播放并高亮 |
| **文字转音符** | 输入文本（仅 A–Z，空格为休止符）→ 生成音符序列 |
| **序列演奏** | Web Audio 正弦波 + 指数包络，按 0.42s/音符顺序演奏，琴键与字母同步高亮 |

**密码学对应**：演示"编码 / 码本"概念——同样的 26 个字母，映射方式不同（码本不同），得到的"密文音乐"就不同，是替代密码与一次一密思想的雏形。

### 模块四：音乐哈希

| 功能 | 说明 |
|------|------|
| **感知哈希 pHash** | 音频归一化为 8×8 频谱 → 2D DCT → 中值二值化 → 64-bit；以二进制 + 十六进制 + 8×8 位图展示 |
| **鲁棒性演示** | 修改 1 采样点 / 混入轻微噪声后重算，显示汉明距离（通常 0–8 bit） |
| **密码学哈希 SHA-256** | WebCrypto 对解码音频（统一 16-bit WAV 字节）计算；修改 1 采样点后重算，展示雪崩效应（约一半比特翻转） |
| **频谱指纹匹配** | 简化 Shazam：分帧 → FFT → 提取频谱峰值对 → (f1,f2) 哈希表；任意 3 秒片段可匹配到参考音频中的准确位置（投票柱状图可视化） |

**密码学对应**：对比感知哈希与密码学哈希的本质——pHash 反映"听起来像什么"（小扰动 → 小变化），SHA-256 反映"字节是什么"（1 位改动 → 雪崩），对应哈希函数特性的直觉理解。

### 模块五：单表替代密码

用音乐实现最早的加密法——单表替代（凯撒 / 仿射），并演示**频率分析破解**：

| 功能 | 说明 |
|------|------|
| **音乐凯撒** | `C = (P + k) mod 26`，密钥滑块 0–25；同一明文换密钥 → 密文音乐旋律不同 |
| **音乐仿射** | `C = (a·P + b) mod 26`，a 需与 26 互质（12 种选择）+ b 滑块 |
| **密文→音符** | 复用「音乐密码本」映射（A–U→白键，V–Z→黑键），密文字母播放为固定音高；26 个字母键条带播放时高亮 |
| **频率指纹** | Canvas 柱状图：密文字母频率（蓝）vs 英语字母参考（灰）并排——形状几乎一致，直观看出"换了名字没换频率" |
| **自动破解** | 暴力尝试全部 312 种仿射密钥（含凯撒特例 a=1），卡方检验选出最像英语的明文，返回检测到的 方法 + 密钥 + 恢复文本 + Top 3 候选 |
| **交互式猜测** | 26 个"密文 → 猜测明文"下拉框，改任意一项实时重算恢复的明文；可对照原始明文看正确率 |

**密码学对应**：说明密钥空间——凯撒仅 26 种、仿射 312 种、任意单表替代 26! ≈ 4×10²⁶ 种，但频率分析（单表替代保留字母频率）能全部击破；同时演示"文本越短，统计噪声越大，越难破译"。

### 模块六：维吉尼亚多表替代密码

从单表替代进阶到多表替代，理解为什么维吉尼亚密码曾被认为是"不可破译的"：

| 功能 | 说明 |
|------|------|
| **维吉尼亚加密** | `C = (P + K) mod 26`，密钥词循环移位；同一明文不同密钥 → 密文旋律完全不同 |
| **频率分析** | Canvas 柱状图展示密文字母频率分布，维吉尼亚会将分布"压平"令单表分析失效 |
| **重合指数 (IC)** | 计算密文的平均重合指数，对比英语（0.066）和随机文本（0.038），判断是否为多表替代 |
| **卡西斯基测试** | 三连字重复间距分析，统计间距的公因数推断密钥长度 |
| **密钥长度检测** | 自动检测密钥长度（IC 法 + 卡西斯基），结果可视化为 IC 柱状图 |
| **逐列频率分析** | 按密钥长度分组，每组用单表凯撒破解（卡方检验），恢复完整密钥 |
| **密文音乐播放** | 26 个字母键条带试听 + 播放时高亮同步，感受多表替代的复杂性 |
| **交互式恢复** | 可调密钥长度滑块，实时重新计算恢复的明文，显示与原文的匹配度 |

**密码学对应**：维吉尼亚通过多个凯撒密码轮换，使单字母频率分析失效；但通过重合指数和卡西斯基测试可以推断密钥长度，再用逐列凯撒破解恢复密钥——演示了"复杂性可以被分解"的密码分析思想。

## 兼容性支持矩阵
| 环境 | 状态 | 说明 |
|------|------|------|
| Chrome / Edge（桌面） | ✅ 已实测 | 完整功能 |
| Firefox / Safari | ⏳ 集成测试中 | 已知 Safari 部分音频特性与 Chrome 存在差异，已做特性检测与降级提示 |
| 移动端 | ⚠️ 部分优化中 | 低配设备高频渲染场景已做分帧渲染与降采样分级；麦克风采集依赖安全上下文 |
| 本地离线运行 | ✅ 支持 | 静态页面 + 本地存储，无需服务器与网络 |
> 已知问题与降级策略持续更新于本表；发现兼容性问题欢迎提交 Issue。

## 使用方式

直接在浏览器打开 `index.html` 即可使用（推荐 Chrome / Edge）。顶部 Tab 切换六大模块：

**♩ 音频可视化**：
- 信号发生器：调节频率和波形，观察时域/频域变化
- 音频文件：选择本地音频文件，播放时观察波形与频谱

**♯ 音频隐写术**：
- 编码：在载体音频中隐藏秘密消息，下载为 WAV
- 解码：从隐写音频中提取隐藏消息

**♫ 音乐密码本**：
- 点击钢琴琴键试听，观察音名/唱名/字母标注（白键 A–U，黑键 V–Z），可用复选框切换显示
- 点击琴键高亮映射表字母，点击字母演奏对应琴键
- 演示音阶（大调/小调/五声/半音）
- 输入文字（如 HELLO WORLD）→ 转换为音符序列 → 播放

**♬ 音乐哈希**：
- 选择音频文件 → 计算感知哈希（二进制/十六进制/8×8 位图）
- 用「修改 1 采样点」「混入轻微噪声」对比 pHash 的鲁棒性与 SHA-256 的雪崩效应
- 提取参考指纹后，用滑块选择片段位置 → 「匹配 3 秒片段」观察匹配偏移与投票柱状图

**♪ 替代密码**：
- 输入明文 → 选方法（凯撒/仿射）+ 调密钥 → 「加密并生成密文音乐」，观察密文与音符序列
- 「播放密文音乐」听同一明文在不同密钥下的旋律差异，26 个字母键同步高亮
- 「频率分析」卡片：查看密文字母频率柱状图（蓝柱）与英语参考（灰柱）的相似形状
- 「自动破解」：尝试全部 312 种仿射密钥，看检测出的方法/密钥/恢复明文；再用猜测表手动微调，开启「显示原始明文对照」验证正确率

**♭ 维吉尼亚密码**：
- 输入明文 + 密钥词 → 加密 → 观察密文字母频率分布如何被"压平"
- 「播放密文音乐」感受多表替代的复杂性，26 个字母键同步高亮
- 「检测密钥长度」：自动分析重合指数 (IC) 和卡西斯基测试，推断密钥长度
- 「恢复明文」：按检测到的密钥长度逐列频率分析，自动恢复密钥和明文
- 调整密钥长度滑块，实时重新计算恢复结果，对比原文验证正确率

## 教学路线

| 周次 | 模块 | 密码学概念 |
|------|------|-----------|
| 第 1 周 | 音频可视化 | 信号、时域/频域 |
| 第 2 周 | 音频隐写术 | LSB 替换、隐蔽信道、鲁棒性 |
| 第 3 周 | 音乐密码本 | 编码、码本 |
| 第 4 周 | 音乐哈希 | 指纹、单向函数、雪崩效应 |
| 第 5 周 | 替代密码 | 替换密码、频率分析 |
| 第 6 周 | 维吉尼亚密码 | 多表替代、卡西斯基攻击 |
| 第 7 周 | 组合应用（规划） | 综合实践 |

## 技术栈

- **零外部依赖**：纯手写，无需任何 npm 包
- **Web Audio API**：音频解码、分析节点、实时处理
- **Canvas 2D**：波形与频谱可视化渲染
- **FFT**：自实现 Cooley-Tukey 蝶形算法
- **响应式布局**：桌面双栏 / 移动端单栏自适应

---

## 隐私与安全
- **数据不出设备**：所有运算在浏览器本地完成，进度仅存于 `localStorage`，无账号体系、无后端服务器、无任何数据上传；
- **零第三方音频素材**：全部音色由 Web Audio 程序合成（正弦波等），不含任何外部版权音频。

## 合规与使用声明
- 本平台仅用于**密码学教学与科普演示**，禁止用于任何非法用途；平台不提供在线隐蔽通信托管服务；
- 平台为教学演示工具，不涉及《中华人民共和国密码法》所规制的商用密码产品研发、销售或认证。