🎵 SonicForge

轻量级本地AI音乐生成工作站 | Lightweight Local AI Music Generation Workstation

简体中文 | 繁體中文 | English

🎉 项目介绍

SonicForge 是一款轻量级本地AI音乐生成工作站，旨在让每一位开发者和音乐爱好者都能在本地环境中生成高质量音乐。

核心价值

在本地环境中生成高质量音乐，无需依赖任何云端服务，充分保护用户隐私。所有计算均在本地完成，数据不离开你的机器。

解决的痛点

现有的AI音乐生成工具普遍存在以下问题：

付费订阅门槛：如 Suno 等平台需要付费订阅，生成次数受限
环境配置复杂：许多开源项目依赖 CUDA、PyTorch 等重型框架，配置繁琐
GPU资源依赖：大部分AI音乐工具需要高性能GPU才能运行
隐私安全隐患：云端生成意味着你的创意数据需要上传到第三方服务器

自研差异化亮点

多模型插件架构：内置3种音乐生成模型，支持通过插件机制轻松扩展
零前端框架依赖：纯原生 HTML/CSS/JS 构建，无需 Node.js 构建工具链
专业级参数控制：BPM、调性、风格、乐器、温度等参数精细可调
RESTful API 可集成：提供10个标准化API端点，可被其他应用和服务集成

💡 灵感来源：本项目受 GitHub Trending 热门项目 ace-step-ui 启发，独立自研开发，从架构设计到核心实现均为原创。

✨ 核心特性

特性	说明
🎵 多模型支持	内置3种音乐生成模型（Sine Wave Basic、Harmonic Synthesizer、Rhythm Engine），支持插件扩展
🖥️ 专业工作站UI	深色主题，渐变色设计，响应式布局，提供沉浸式创作体验
🎛️ 精细参数控制	BPM、调性、风格、乐器、温度、采样率等专业参数全面可调
📦 插件化架构	基于抽象基类的模型接口，轻松添加新的音乐生成模型
🔊 实时波形可视化	Canvas 绘制的音频波形展示，生成结果即时预览
💾 本地项目管理	生成历史记录管理，一键导出 WAV/MP3 格式
🌐 RESTful API	10个标准化API端点，可被其他应用和服务集成调用
🧪 完善测试	57个单元测试，覆盖配置、模型管理、生成引擎、音频工具、导出器、API等全部核心模块
🚀 零前端依赖	纯原生 HTML/CSS/JS，无需 Node.js、npm 或任何构建工具

🚀 快速开始

环境要求

Python 3.8 或更高版本
pip（Python 包管理器）

安装步骤

# 克隆仓库
git clone https://github.com/gitstq/SonicForge.git
cd SonicForge

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# 安装依赖
pip install -r requirements.txt

启动服务

# 默认启动（监听 0.0.0.0:7860）
python app.py

# 自定义端口
python app.py --port 8080

# 开启调试模式
python app.py --debug

启动成功后，在浏览器中访问：

http://localhost:7860

🎉 打开浏览器即可看到 SonicForge 的专业工作站界面，开始你的音乐创作之旅！

📖 详细使用指南

Web 界面使用说明

选择模型：在顶部模型选择区域，从内置的3种模型中选择一个
设置参数：调整 BPM、调性、风格、乐器、温度等参数
输入提示词：在文本框中描述你想要的音乐风格（可选）
生成音乐：点击生成按钮，等待异步任务完成
预览与导出：在波形可视化区域预览结果，一键导出为 WAV 或 MP3

API 调用示例

健康检查

curl http://localhost:7860/api/health

获取可用模型列表

curl http://localhost:7860/api/models

加载指定模型

curl -X POST http://localhost:7860/api/models/harmonic_synthesizer/load

生成音乐

curl -X POST http://localhost:7860/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一段轻快的电子音乐",
    "duration": 10,
    "bpm": 128,
    "key": "Am",
    "genre": "Electronic",
    "instrument": "Synth",
    "temperature": 0.7
  }'

查询生成状态

curl http://localhost:7860/api/generate/<task_id>/status

下载生成结果

curl -O http://localhost:7860/api/generate/<task_id>/download

获取生成历史

curl http://localhost:7860/api/history?limit=20

导出指定历史记录

curl -X POST http://localhost:7860/api/export/<item_id> \
  -H "Content-Type: application/json" \
  -d '{"format": "wav"}'

获取/更新设置

# 获取当前设置
curl http://localhost:7860/api/settings

# 更新设置
curl -X PUT http://localhost:7860/api/settings \
  -H "Content-Type: application/json" \
  -d '{"default_bpm": 140, "default_key": "Am"}'

参数说明

参数	类型	默认值	说明
`prompt`	string	`""`	音乐描述提示词
`duration`	float	`10.0`	生成时长（秒），最大60秒
`bpm`	int	`120`	每分钟节拍数
`key`	string	`"C"`	调性，支持 C, C#, D, ..., B, Cm, Dm, ..., Bm
`genre`	string	`"Electronic"`	音乐风格（Electronic, Ambient, Classical, Pop, Rock, Jazz, Hip-Hop, Lo-Fi）
`instrument`	string	`"Synth"`	乐器类型（Synth, Piano, Guitar, Bass, Drums, Organ, Percussion）
`temperature`	float	`0.7`	生成随机性控制，0.0-1.0，值越高越有创造性
`sample_rate`	int	`44100`	采样率（Hz）
`seed`	int	`null`	随机种子，指定后可复现生成结果

典型使用场景

快速原型：使用 Sine Wave Basic 模型快速测试和验证音乐创意
和弦编配：使用 Harmonic Synthesizer 模型生成和弦进行
节奏编排：使用 Rhythm Engine 模型创建鼓点和节奏模式
API集成：通过 RESTful API 将音乐生成能力集成到你的应用中

💡 设计思路与迭代规划

设计理念

SonicForge 遵循以下核心设计原则：

本地优先：所有计算在本地完成，保护用户隐私
轻量简洁：最小化依赖，无需 GPU，普通电脑即可运行
插件化扩展：基于抽象基类的模型接口，新模型只需实现3个方法
API驱动：所有功能通过 RESTful API 暴露，便于集成

技术选型原因

技术	选型原因
Python	音频处理生态丰富（NumPy, SciPy），开发效率高
Flask	轻量级Web框架，适合工具类应用，学习成本低
原生 HTML/CSS/JS	零构建依赖，部署简单，加载速度快
NumPy	高性能数值计算，音频信号处理的核心库
Canvas API	浏览器原生波形可视化，无需额外图表库

后续计划

GPU 模型支持：集成基于深度学习的音乐生成模型（需 GPU）
更多导出格式：支持 FLAC、OGG 等音频格式
MIDI 支持：导入/导出 MIDI 文件，支持乐谱级编辑
实时流式生成：WebSocket 支持的实时音频流
模型市场：社区模型分享与下载平台
多轨混音：多轨道叠加与混音功能
音频效果器：内置混响、延迟、均衡器等效果

📦 打包与部署指南

本地运行

最简单的运行方式，适合开发和测试：

git clone https://github.com/gitstq/SonicForge.git
cd SonicForge
pip install -r requirements.txt
python app.py

Docker 部署

使用 Docker 容器化部署，适合生产环境：

FROM python:3.10-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# 安装 Python 依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目文件
COPY . .

# 创建输出目录
RUN mkdir -p /app/output /app/temp

# 暴露端口
EXPOSE 7860

# 启动应用
CMD ["python", "app.py", "--host", "0.0.0.0", "--port", "7860"]

构建并运行：

# 构建镜像
docker build -t sonicforge .

# 运行容器
docker run -d -p 7860:7860 -v ./output:/app/output sonicforge

生产环境部署建议

⚠️ 安全提示：生产环境部署时，请务必修改 SECRET_KEY 并启用 HTTPS。

使用 Gunicorn 作为 WSGI 服务器：

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:7860 "app:create_app()"

使用 Nginx 反向代理：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:7860;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

环境变量配置：

export SONICFORGE_HOST=0.0.0.0
export SONICFORGE_PORT=7860
export SONICFORGE_DEBUG=false
export SONICFORGE_OUTPUT_PATH=/data/sonicforge/output
export SONICFORGE_MAX_DURATION=60

🤝 贡献指南

我们欢迎并感谢每一位贡献者！请遵循以下规范：

PR 提交规范

Fork 本仓库并创建特性分支：git checkout -b feature/your-feature-name
确保所有测试通过：python -m pytest tests/ -v
提交信息遵循 Conventional Commits 规范：
- feat: 添加新功能
- fix: 修复Bug
- docs: 更新文档
- refactor: 代码重构
- test: 添加或修改测试
推送并创建 Pull Request

Issue 反馈规则

使用清晰的标题描述问题
提供复现步骤和环境信息（Python版本、操作系统等）
附上相关的日志输出或截图
功能建议请标注 [Feature Request] 前缀

📄 开源协议

本项目基于 MIT License 开源。

MIT License

Copyright (c) 2024 SonicForge

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

🎉 專案介紹

SonicForge 是一款輕量級本地AI音樂生成工作站，旨在讓每一位開發者和音樂愛好者都能在本地環境中生成高品質音樂。

核心價值

在本地環境中生成高品質音樂，無需依賴任何雲端服務，充分保護使用者隱私。所有運算均在本地完成，資料不會離開你的機器。

解決的痛點

現有的AI音樂生成工具普遍存在以下問題：

付費訂閱門檻：如 Suno 等平台需要付費訂閱，生成次數受限
環境配置複雜：許多開源專案依賴 CUDA、PyTorch 等重型框架，配置繁瑣
GPU資源依賴：大部分AI音樂工具需要高效能GPU才能運行
隱私安全隱患：雲端生成意味著你的創意資料需要上傳到第三方伺服器

自研差異化亮點

多模型插件架構：內建3種音樂生成模型，支援透過插件機制輕鬆擴展
零前端框架依賴：純原生 HTML/CSS/JS 建構，無需 Node.js 建構工具鏈
專業級參數控制：BPM、調性、風格、樂器、溫度等參數精細可調
RESTful API 可整合：提供10個標準化API端點，可被其他應用和服務整合

💡 靈感來源：本專案受 GitHub Trending 熱門專案 ace-step-ui 啟發，獨立自研開發，從架構設計到核心實現均為原創。

✨ 核心特性

特性	說明
🎵 多模型支援	內建3種音樂生成模型（Sine Wave Basic、Harmonic Synthesizer、Rhythm Engine），支援插件擴展
🖥️ 專業工作站UI	深色主題，漸層色設計，響應式佈局，提供沉浸式創作體驗
🎛️ 精細參數控制	BPM、調性、風格、樂器、溫度、取樣率等專業參數全面可調
📦 插件化架構	基於抽象基類的模型介面，輕鬆添加新的音樂生成模型
🔊 即時波形視覺化	Canvas 繪製的音頻波形展示，生成結果即時預覽
💾 本地專案管理	生成歷史記錄管理，一鍵匯出 WAV/MP3 格式
🌐 RESTful API	10個標準化API端點，可被其他應用和服務整合呼叫
🧪 完善測試	57個單元測試，覆蓋設定、模型管理、生成引擎、音頻工具、匯出器、API等全部核心模組
🚀 零前端依賴	純原生 HTML/CSS/JS，無需 Node.js、npm 或任何建構工具

🚀 快速開始

環境需求

Python 3.8 或更高版本
pip（Python 套件管理器）

安裝步驟

# 複製仓库
git clone https://github.com/gitstq/SonicForge.git
cd SonicForge

# 建立虛擬環境（推薦）
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# 安裝依賴
pip install -r requirements.txt

啟動服務

# 預設啟動（監聽 0.0.0.0:7860）
python app.py

# 自訂連接埠
python app.py --port 8080

# 開啟除錯模式
python app.py --debug

啟動成功後，在瀏覽器中造訪：

http://localhost:7860

🎉 開啟瀏覽器即可看到 SonicForge 的專業工作站介面，開始你的音樂創作之旅！

📖 詳細使用指南

Web 介面使用說明

選擇模型：在頂部模型選擇區域，從內建的3種模型中選擇一個
設定參數：調整 BPM、調性、風格、樂器、溫度等參數
輸入提示詞：在文字框中描述你想要的音樂風格（可選）
生成音樂：點擊生成按鈕，等待非同步任務完成
預覽與匯出：在波形視覺化區域預覽結果，一鍵匯出為 WAV 或 MP3

API 呼叫範例

健康檢查

curl http://localhost:7860/api/health

取得可用模型清單

curl http://localhost:7860/api/models

載入指定模型

curl -X POST http://localhost:7860/api/models/harmonic_synthesizer/load

生成音樂

curl -X POST http://localhost:7860/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一段輕快的電子音樂",
    "duration": 10,
    "bpm": 128,
    "key": "Am",
    "genre": "Electronic",
    "instrument": "Synth",
    "temperature": 0.7
  }'

查詢生成狀態

curl http://localhost:7860/api/generate/<task_id>/status

下載生成結果

curl -O http://localhost:7860/api/generate/<task_id>/download

取得生成歷史

curl http://localhost:7860/api/history?limit=20

匯出指定歷史記錄

curl -X POST http://localhost:7860/api/export/<item_id> \
  -H "Content-Type: application/json" \
  -d '{"format": "wav"}'

取得/更新設定

# 取得當前設定
curl http://localhost:7860/api/settings

# 更新設定
curl -X PUT http://localhost:7860/api/settings \
  -H "Content-Type: application/json" \
  -d '{"default_bpm": 140, "default_key": "Am"}'

參數說明

參數	類型	預設值	說明
`prompt`	string	`""`	音樂描述提示詞
`duration`	float	`10.0`	生成時長（秒），最大60秒
`bpm`	int	`120`	每分鐘節拍數
`key`	string	`"C"`	調性，支援 C, C#, D, ..., B, Cm, Dm, ..., Bm
`genre`	string	`"Electronic"`	音樂風格（Electronic, Ambient, Classical, Pop, Rock, Jazz, Hip-Hop, Lo-Fi）
`instrument`	string	`"Synth"`	樂器類型（Synth, Piano, Guitar, Bass, Drums, Organ, Percussion）
`temperature`	float	`0.7`	生成隨機性控制，0.0-1.0，值越高越有創造性
`sample_rate`	int	`44100`	取樣率（Hz）
`seed`	int	`null`	隨機種子，指定後可重現生成結果

典型使用場景

快速原型：使用 Sine Wave Basic 模型快速測試和驗證音樂創意
和弦編配：使用 Harmonic Synthesizer 模型生成和弦進行
節奏編排：使用 Rhythm Engine 模型創建鼓點和節奏模式
API整合：透過 RESTful API 將音樂生成能力整合到你的應用中

💡 設計思路與迭代規劃

設計理念

SonicForge 遵循以下核心設計原則：

本地優先：所有運算在本地完成，保護使用者隱私
輕量簡潔：最小化依賴，無需 GPU，一般電腦即可運行
插件化擴展：基於抽象基類的模型介面，新模型只需實作3個方法
API驅動：所有功能透過 RESTful API 暴露，便於整合

技術選型原因

技術	選型原因
Python	音頻處理生態豐富（NumPy, SciPy），開發效率高
Flask	輕量級Web框架，適合工具類應用，學習成本低
原生 HTML/CSS/JS	零建構依賴，部署簡單，載入速度快
NumPy	高效能數值運算，音頻訊號處理的核心函式庫
Canvas API	瀏覽器原生波形視覺化，無需額外圖表函式庫

後續計畫

GPU 模型支援：整合基於深度學習的音樂生成模型（需 GPU）
更多匯出格式：支援 FLAC、OGG 等音頻格式
MIDI 支援：匯入/匯出 MIDI 檔案，支援樂譜級編輯
即時串流生成：WebSocket 支援的即時音頻串流
模型市場：社群模型分享與下載平台
多軌混音：多軌道疊加與混音功能
音頻效果器：內建殘響、延遲、等化器等效果

📦 打包與部署指南

本地運行

最簡單的運行方式，適合開發和測試：

git clone https://github.com/gitstq/SonicForge.git
cd SonicForge
pip install -r requirements.txt
python app.py

Docker 部署

使用 Docker 容器化部署，適合生產環境：

FROM python:3.10-slim

WORKDIR /app

# 安裝系統依賴
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# 安裝 Python 依賴
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 複製專案檔案
COPY . .

# 建立輸出目錄
RUN mkdir -p /app/output /app/temp

# 暴露連接埠
EXPOSE 7860

# 啟動應用
CMD ["python", "app.py", "--host", "0.0.0.0", "--port", "7860"]

建置並運行：

# 建置映像檔
docker build -t sonicforge .

# 運行容器
docker run -d -p 7860:7860 -v ./output:/app/output sonicforge

生產環境部署建議

⚠️ 安全提示：生產環境部署時，請務必修改 SECRET_KEY 並啟用 HTTPS。

使用 Gunicorn 作為 WSGI 伺服器：

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:7860 "app:create_app()"

使用 Nginx 反向代理：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:7860;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

環境變數配置：

export SONICFORGE_HOST=0.0.0.0
export SONICFORGE_PORT=7860
export SONICFORGE_DEBUG=false
export SONICFORGE_OUTPUT_PATH=/data/sonicforge/output
export SONICFORGE_MAX_DURATION=60

🤝 貢獻指南

我們歡迎並感謝每一位貢獻者！請遵循以下規範：

PR 提交規範

Fork 本倉庫並建立特性分支：git checkout -b feature/your-feature-name
確保所有測試通過：python -m pytest tests/ -v
提交訊息遵循 Conventional Commits 規範：
- feat: 新增新功能
- fix: 修復Bug
- docs: 更新文件
- refactor: 程式碼重構
- test: 新增或修改測試
推送並建立 Pull Request

Issue 回饋規則

使用清晰的標題描述問題
提供重現步驟和環境資訊（Python版本、作業系統等）
附上相關的日誌輸出或截圖
功能建議請標註 [Feature Request] 前綴

📄 開源協議

本專案基於 MIT License 開源。

MIT License

Copyright (c) 2024 SonicForge

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

你可以自由使用、修改和分發本專案，包括用於商業用途。唯一的條件是保留版權宣告和許可宣告。

🎉 Introduction

SonicForge is a lightweight local AI music generation workstation designed to empower developers and music enthusiasts to create high-quality music entirely on their local machine.

Core Value

Generate high-quality music in a local environment without relying on any cloud services, ensuring complete privacy protection. All computation happens on your machine -- your creative data never leaves it.

Problems We Solve

Existing AI music generation tools suffer from several common issues:

Subscription paywalls: Platforms like Suno require paid subscriptions with limited generation quotas
Complex setup: Many open-source projects depend on CUDA, PyTorch, and other heavy frameworks with tedious configuration
GPU dependency: Most AI music tools require a high-performance GPU to function
Privacy concerns: Cloud-based generation means uploading your creative data to third-party servers

What Makes SonicForge Different

Multi-model plugin architecture: 3 built-in music generation models with a plugin system for easy extension
Zero frontend framework dependency: Built with vanilla HTML/CSS/JS -- no Node.js build toolchain required
Professional parameter control: Fine-grained control over BPM, key, genre, instrument, temperature, and more
RESTful API integration: 10 standardized API endpoints for seamless integration with other applications

💡 Inspiration: This project was inspired by the GitHub Trending project ace-step-ui. SonicForge is independently developed with original architecture design and core implementation.

✨ Key Features

Feature	Description
🎵 Multi-model support	3 built-in models (Sine Wave Basic, Harmonic Synthesizer, Rhythm Engine) with plugin extension support
🖥️ Professional workstation UI	Dark theme with gradient design and responsive layout for an immersive creative experience
🎛️ Fine-grained parameter control	Full control over BPM, key, genre, instrument, temperature, sample rate, and more
📦 Plugin-based architecture	Abstract base class model interface -- add new models by implementing just 3 methods
🔊 Real-time waveform visualization	Canvas-based audio waveform display with instant preview of generation results
💾 Local project management	Generation history management with one-click WAV/MP3 export
🌐 RESTful API	10 standardized API endpoints for integration with other applications and services
🧪 Comprehensive testing	57 unit tests covering configuration, model management, generation engine, audio utilities, exporter, and API
🚀 Zero frontend dependencies	Pure vanilla HTML/CSS/JS -- no Node.js, npm, or build tools required

🚀 Quick Start

Prerequisites

Python 3.8 or later
pip (Python package manager)

Installation

# Clone the repository
git clone https://github.com/gitstq/SonicForge.git
cd SonicForge

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

Launch the Server

# Start with defaults (listens on 0.0.0.0:7860)
python app.py

# Custom port
python app.py --port 8080

# Enable debug mode
python app.py --debug

Once the server is running, open your browser and navigate to:

http://localhost:7860

🎉 You'll see the SonicForge professional workstation interface -- start creating music right away!

📖 Detailed Usage Guide

Web Interface

Select a model: Choose from one of the 3 built-in models in the model selector
Configure parameters: Adjust BPM, key, genre, instrument, temperature, and other settings
Enter a prompt: Describe the music style you want in the text field (optional)
Generate: Click the generate button and wait for the async task to complete
Preview & export: Preview the result in the waveform visualizer and export as WAV or MP3

API Examples

Health Check

curl http://localhost:7860/api/health

List Available Models

curl http://localhost:7860/api/models

Load a Specific Model

curl -X POST http://localhost:7860/api/models/harmonic_synthesizer/load

Generate Music

curl -X POST http://localhost:7860/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "An upbeat electronic track",
    "duration": 10,
    "bpm": 128,
    "key": "Am",
    "genre": "Electronic",
    "instrument": "Synth",
    "temperature": 0.7
  }'

Check Generation Status

curl http://localhost:7860/api/generate/<task_id>/status

Download Generated Audio

curl -O http://localhost:7860/api/generate/<task_id>/download

Get Generation History

curl http://localhost:7860/api/history?limit=20

Export a History Item

curl -X POST http://localhost:7860/api/export/<item_id> \
  -H "Content-Type: application/json" \
  -d '{"format": "wav"}'

Get/Update Settings

# Get current settings
curl http://localhost:7860/api/settings

# Update settings
curl -X PUT http://localhost:7860/api/settings \
  -H "Content-Type: application/json" \
  -d '{"default_bpm": 140, "default_key": "Am"}'

Parameter Reference

Parameter	Type	Default	Description
`prompt`	string	`""`	Text description of the desired music
`duration`	float	`10.0`	Generation duration in seconds (max 60)
`bpm`	int	`120`	Beats per minute
`key`	string	`"C"`	Musical key (C, C#, D, ..., B, Cm, Dm, ..., Bm)
`genre`	string	`"Electronic"`	Music genre (Electronic, Ambient, Classical, Pop, Rock, Jazz, Hip-Hop, Lo-Fi)
`instrument`	string	`"Synth"`	Instrument type (Synth, Piano, Guitar, Bass, Drums, Organ, Percussion)
`temperature`	float	`0.7`	Randomness control, 0.0-1.0; higher values produce more creative output
`sample_rate`	int	`44100`	Audio sample rate in Hz
`seed`	int	`null`	Random seed for reproducible generation

Use Cases

Rapid prototyping: Use the Sine Wave Basic model to quickly test and validate musical ideas
Chord composition: Use the Harmonic Synthesizer model to generate chord progressions
Rhythm programming: Use the Rhythm Engine model to create drum patterns and beats
API integration: Integrate music generation capabilities into your own applications via the RESTful API

💡 Design Philosophy & Roadmap

Design Principles

SonicForge is built on these core principles:

Local-first: All computation runs locally to protect user privacy
Lightweight & simple: Minimal dependencies, no GPU required, runs on any standard computer
Plugin-based extensibility: Abstract base class model interface -- new models only need to implement 3 methods
API-driven: All functionality exposed via RESTful API for easy integration

Technology Choices

Technology	Rationale
Python	Rich audio processing ecosystem (NumPy, SciPy) with high development efficiency
Flask	Lightweight web framework ideal for utility applications with a low learning curve
Vanilla HTML/CSS/JS	Zero build dependencies, simple deployment, fast page loads
NumPy	High-performance numerical computing -- the backbone of audio signal processing
Canvas API	Browser-native waveform visualization without additional charting libraries

Roadmap

GPU model support: Integrate deep learning-based music generation models (GPU required)
Additional export formats: Support for FLAC, OGG, and other audio formats
MIDI support: Import/export MIDI files with score-level editing
Real-time streaming: WebSocket-based real-time audio streaming
Model marketplace: Community model sharing and download platform
Multi-track mixing: Multi-track layering and mixing capabilities
Audio effects: Built-in reverb, delay, EQ, and other effects

📦 Packaging & Deployment

Local Development

The simplest way to get started, ideal for development and testing:

git clone https://github.com/gitstq/SonicForge.git
cd SonicForge
pip install -r requirements.txt
python app.py

Docker Deployment

Containerized deployment using Docker, suitable for production environments:

FROM python:3.10-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy project files
COPY . .

# Create output directories
RUN mkdir -p /app/output /app/temp

# Expose port
EXPOSE 7860

# Start the application
CMD ["python", "app.py", "--host", "0.0.0.0", "--port", "7860"]

Build and run:

# Build the image
docker build -t sonicforge .

# Run the container
docker run -d -p 7860:7860 -v ./output:/app/output sonicforge

Production Deployment

⚠️ Security note: For production deployments, always change the SECRET_KEY and enable HTTPS.

Use Gunicorn as the WSGI server:

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:7860 "app:create_app()"

Set up Nginx as a reverse proxy:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:7860;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Environment variable configuration:

export SONICFORGE_HOST=0.0.0.0
export SONICFORGE_PORT=7860
export SONICFORGE_DEBUG=false
export SONICFORGE_OUTPUT_PATH=/data/sonicforge/output
export SONICFORGE_MAX_DURATION=60

🤝 Contributing

We welcome and appreciate every contributor! Please follow these guidelines:

Pull Request Guidelines

Fork this repository and create a feature branch: git checkout -b feature/your-feature-name
Ensure all tests pass: python -m pytest tests/ -v
Follow the Conventional Commits specification for commit messages:
- feat: add new feature
- fix: fix a bug
- docs: update documentation
- refactor: code refactoring
- test: add or modify tests
Push your changes and create a Pull Request

Issue Reporting

Use a clear and descriptive title
Provide reproduction steps and environment details (Python version, OS, etc.)
Include relevant log output or screenshots
Prefix feature requests with [Feature Request]

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2024 SonicForge

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

You are free to use, modify, and distribute this project, including for commercial purposes. The only condition is that you retain the copyright notice and license declaration.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
api		api
core		core
models		models
static		static
templates		templates
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
app.py		app.py
config.py		config.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

🎵 SonicForge

🎉 项目介绍

核心价值

解决的痛点

自研差异化亮点

✨ 核心特性

🚀 快速开始

环境要求

安装步骤

启动服务

📖 详细使用指南

Web 界面使用说明

API 调用示例

健康检查

获取可用模型列表

加载指定模型

生成音乐

查询生成状态

下载生成结果

获取生成历史

导出指定历史记录

获取/更新设置

参数说明

典型使用场景

💡 设计思路与迭代规划

设计理念

技术选型原因

后续计划

📦 打包与部署指南

本地运行

Docker 部署

生产环境部署建议

🤝 贡献指南

PR 提交规范

Issue 反馈规则

📄 开源协议

🎉 專案介紹

核心價值

解決的痛點

自研差異化亮點

✨ 核心特性

🚀 快速開始

環境需求

安裝步驟

啟動服務

📖 詳細使用指南

Web 介面使用說明

API 呼叫範例

健康檢查

取得可用模型清單

載入指定模型

生成音樂

查詢生成狀態

下載生成結果

取得生成歷史

匯出指定歷史記錄

取得/更新設定

參數說明

典型使用場景

💡 設計思路與迭代規劃

設計理念

技術選型原因

後續計畫

📦 打包與部署指南

本地運行

Docker 部署

生產環境部署建議

🤝 貢獻指南

PR 提交規範

Issue 回饋規則

📄 開源協議

🎉 Introduction

Core Value

Problems We Solve

What Makes SonicForge Different

✨ Key Features

Packages