WaveBox

一款精心打造的 iOS 原生电台应用，用声音连接世界

---

简介

WaveBox 是一款 iOS 原生电台播放应用，采用 SwiftUI + UIKit 混合架构，支持 HLS 和 Icecast/Shoutcast 音频流。应用以「钛金属」为设计语言，提供沉浸式的收听体验。

无论是通勤路上、睡前放松，还是工作时的背景音乐，WaveBox 都能为你提供流畅、稳定的电台收听服务。

功能特性

功能	描述
直播电台	支持 HLS (m3u8) 和 Icecast/Shoutcast 音频流
后台播放	完整的后台音频支持 + 锁屏播放控制
睡眠定时器	设定时间后自动停止播放，定时数据持久化
收藏系统	一键收藏喜爱的电台，快速访问
横屏模式	基于 Size Classes 的沉浸式横屏体验
Widget	Now Playing + 控制台 Widget，桌面快捷操控
波形可视化	实时音频波形动画效果
触觉反馈	精心调校的 Haptic 交互体验

技术栈

框架层      SwiftUI 5 + UIKit (AppDelegate 生命周期)
音频引擎    AVFoundation (AVPlayer) + MediaPlayer
响应式      Combine 框架
Widget      WidgetKit + App Intents
跨进程通信  App Group + Darwin Notification Center
日志系统    os.Logger (统一日志)
设计系统    自定义 Design Tokens + 钛金属主题
最低版本    iOS 17.0

快速开始

环境要求

• Xcode 15.0+
• iOS 17.0+ 设备或模拟器
• macOS Sonoma 14.0+

构建步骤

# 1. 克隆仓库
git clone https://github.com/Ally1212/WaveBox-OpenSource.git

# 2. 进入项目目录
cd WaveBox-OpenSource

# 3. 用 Xcode 打开项目
open WaveBox.xcodeproj

# 4. 选择目标设备，点击 Run (⌘R)

项目无第三方依赖，克隆后即可直接构建运行。

项目结构

WaveBox-OpenSource/
├── WaveBox/                        # 主应用
│   ├── Sources/
│   │   ├── WaveBoxApp.swift        # 应用入口
│   │   ├── Models/                 # 数据模型
│   │   │   ├── AppState.swift      # 全局状态管理
│   │   │   ├── Station.swift       # 电台模型
│   │   │   └── SoundSource.swift   # 音源类型
│   │   ├── Services/               # 核心服务
│   │   │   └── AudioPlayerService.swift  # 音频播放引擎
│   │   ├── Views/                  # UI 视图
│   │   │   ├── PlayerView.swift    # 主播放器
│   │   │   ├── LandscapePlayerView.swift # 横屏播放
│   │   │   ├── OnboardingView.swift      # 引导页
│   │   │   └── Components/        # 可复用组件
│   │   ├── Extensions/            # 扩展工具
│   │   │   ├── Theme.swift        # 主题系统
│   │   │   └── DesignTokens.swift # 设计令牌
│   │   └── Shared/                # 共享数据层
│   │       └── SharedUserDefaults.swift  # Widget 数据同步
│   └── Assets.xcassets/           # 资源文件
│
├── WaveBoxWidget/                 # Widget 扩展
│   ├── NowPlayingWidget.swift     # 正在播放 Widget
│   ├── ControlConsoleWidget.swift # 控制台 Widget
│   └── Intents/                   # Widget 交互意图
│
├── Design/                        # 设计资源
│   ├── AppIcon/                   # 应用图标
│   └── [UI 设计方案]
│
└── docs/                          # 技术文档

架构设计

┌─────────────────────────────────────────┐
│              Views (SwiftUI)            │
│   PlayerView / LandscapePlayerView      │
│   OnboardingView / SearchView           │
├─────────────────────────────────────────┤
│           AppState (@MainActor)         │
│   播放状态 / 电台管理 / 收藏 / 定时器    │
├─────────────────────────────────────────┤
│      AudioPlayerService (Singleton)     │
│   AVPlayer / AVAudioSession / 锁屏控制  │
├─────────────────────────────────────────┤
│     Shared Layer (App Group)            │
│   SharedUserDefaults / WidgetData       │
├─────────────────────────────────────────┤
│          WidgetKit Extension            │
│   NowPlaying / ControlConsole / Intents │
└─────────────────────────────────────────┘

路线图

• 核心播放功能 (HLS + Icecast)
• 后台音频 + 锁屏控制
• 睡眠定时器
• Widget (Now Playing + 控制台)
• 横屏沉浸模式
• 引导页
• CarPlay 支持
• 播客订阅
• 本地音频文件播放
• 均衡器 (EQ)
• iCloud 同步收藏

贡献指南

欢迎参与 WaveBox 的开发！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: 添加新功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

提交规范: 使用语义化提交 — feat / fix / docs / refactor / test / chore

联系方式

• Issues: GitHub Issues
• 微信: 18932720715
• GitHub: @Ally1212

---

许可证

MIT © 2025 WaveBox

为电台爱好者而做