Universal Tuning Library 🎵 通用音律库

📖 概述

Universal Tuning Library 是一个用C99编写的专业音律计算库，提供35种音律系统的频率生成和转换功能。每个音律系统都基于严谨的数学原理，支持自定义基准频率(A4)，可生成任意数量的音符频率。

✨ 核心特性

• 35种完整音律 — 涵盖西方古典、世界民族、现代高级三大类别
• 纯C实现 — 无外部依赖，易于嵌入音频引擎和嵌入式设备
• 灵活的API — 支持默认配置和自定义参数(基准频率、调式、物理参数等)
• 高精度计算 — 双精度浮点，支持音分偏差计算和频率比率分析
• 模块化设计 — 各音律独立实现，易于扩展新的音律系统
• 频率验证 — 内置频率范围检查(20-20000Hz)，防止无效输出
• 多八度支持 — 可生成任意数量的音符，自动处理八度扩展
• CMake构建 — 支持静态/动态库编译、单元测试、示例程序

⚡ 快速开始

最简单的使用示例：生成一个八度的十二平均律频率：

#include <stdio.h>
#include "tuning_library.h"

int main() {
    double frequencies[12];
    
    // 生成十二平均律 (默认A4=440Hz)
    generate_frequencies_default(TUNING_EQUAL_TEMPERAMENT, frequencies, 12);
    
    // 打印结果
    printf("十二平均律 (A4=440Hz):\n");
    for (int i = 0; i < 12; i++) {
        printf("Note %2d: %.2f Hz\n", i, frequencies[i]);
    }
    
    return 0;
}

📦 编译与安装

Ubuntu/Debian 依赖安装

sudo apt update
sudo apt install build-essential cmake

CMake 构建

git clone https://github.com/example/universal-tuning-library.git
cd universal-tuning-library
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j4
# 运行示例程序
./tuning_example

构建选项

🎼 35种音律详解

🏛️ 西方古典音律 (1-12)

🌍 世界民族音律 (13-18)

🧠 现代高级音律 (19-35)

🏗️ 架构设计

库采用模块化分层架构，各音律独立实现，通过统一的API接口对外提供服务：

📚 API 参考

核心函数

生成指定音律的频率数组。
参数：音律类型、配置(可为NULL)、输出数组、音符数量。
返回：0成功，-1失败。

使用默认配置生成频率(A4=440Hz，12音/八度)。

辅助函数

获取音律名称。

获取音律详细描述。

计算指定音程的频率比率。

计算相对于十二平均律的音分偏差。

打印带音符名称的频率表(C4, C#4, D4...)。

配置结构

typedef struct {
    double base_freq;           // 基准频率 (默认440.0)
    int notes_per_octave;       // 每八度音符数 (默认12)
    double a4_note_index;       // A4的音符索引 (默认9)
    void* custom_params;        // 自定义参数指针
    size_t custom_params_size;  // 自定义参数大小
} TuningConfig;

💡 示例程序

示例1：生成所有音律并对比

#include "tuning_library.h"

int main() {
    double freqs[12];
    
    printf("音律对比 (A4=440Hz):\n");
    printf("音符 | 平均律 | 纯律大调 | 毕达哥拉斯\n");
    printf("-----|--------|----------|-----------\n");
    
    for (int note = 0; note < 12; note++) {
        double eq[1], just[1], pyth[1];
        generate_frequencies_default(TUNING_EQUAL_TEMPERAMENT, eq, note+1);
        generate_frequencies_default(TUNING_JUST_INTONATION_MAJOR, just, note+1);
        generate_frequencies_default(TUNING_PYTHAGOREAN, pyth, note+1);
        
        printf("%4d | %6.2f | %8.2f | %9.2f\n", 
               note, eq[note], just[note], pyth[note]);
    }
    return 0;
}

示例2：自定义基准频率(432Hz和谐调律)

#include "tuning_library.h"

int main() {
    double freqs[12];
    TuningConfig config;
    
    tuning_init_config(&config);
    config.base_freq = 432.0;  // Verdi调律
    
    generate_frequencies(TUNING_EQUAL_TEMPERAMENT, &config, freqs, 12);
    
    printf("432Hz 十二平均律:\n");
    print_frequencies_with_notes(freqs, 12, 432.0);
    
    return 0;
}

示例3：混沌音律生成

#include "tuning_library.h"

int main() {
    double freqs[12];
    TuningConfig config;
    ChaoticParams chaotic = {0.5, 3.9};
    
    tuning_init_config(&config);
    config.custom_params = &chaotic;
    
    generate_frequencies(TUNING_CHAOTIC, &config, freqs, 12);
    
    printf("混沌音律 (logistic map):\n");
    print_frequencies(freqs, 12);
    
    return 0;
}

⚡ 性能测试

在 Intel i7-12700H, 16GB RAM, Ubuntu 22.04 环境下的性能测试结果：

📊 音律对比分析

纯五度比率对比

大三度比率对比

⚖️ 许可证