菜单
Install and use the crystal-audio library for microphone recording, system audio capture, and on-device transcription in Crystal. Covers macOS and iOS platform setup, native extension compilation, and basic recording patterns.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | getting-started |
| description | Install and use the crystal-audio library for microphone recording, system audio capture, and on-device transcription in Crystal. Covers macOS and iOS platform setup, native extension compilation, and basic recording patterns. |
| user-invocable | true |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash |
| version | 0.1.0 |
Add to your shard.yml:
dependencies:
crystal_audio:
github: crimson-knight/crystal-audio
Then run:
shards install
xcode-select --install)brew install crimsonknight/crystal-alphabrew install xcodegenSee the /ios-integration skill for the full iOS guide.
crystal-audio requires C/ObjC extension objects for ObjC runtime bridging, block construction, and system audio capture. Build them before compiling your project:
cd lib/crystal_audio && make ext
This produces:
ext/block_bridge.o — ObjC block ABI for AVFoundation callbacksext/objc_helpers.o — Typed objc_msgSend wrappersext/system_audio_tap.o — ProcessTap / ScreenCaptureKit audio captureYour Crystal build command needs these frameworks linked:
crystal build your_app.cr --link-flags=" \
lib/crystal_audio/ext/block_bridge.o \
lib/crystal_audio/ext/objc_helpers.o \
lib/crystal_audio/ext/system_audio_tap.o \
lib/crystal_audio/ext/audio_write_helper.o \
-framework AVFoundation -framework AudioToolbox \
-framework CoreAudio -framework CoreFoundation \
-framework CoreMedia -framework Foundation \
-framework ScreenCaptureKit"
require "crystal_audio"
rec = CrystalAudio::Recorder.new(
source: CrystalAudio::RecordingSource::Microphone,
output_path: "/tmp/recording.wav"
)
puts "Recording... press Ctrl+C to stop"
rec.start
sleep 10.seconds
rec.stop
puts "Saved to /tmp/recording.wav"
require "crystal_audio"
rec = CrystalAudio::Recorder.new(
source: CrystalAudio::RecordingSource::System,
output_path: "/tmp/system_audio.wav"
)
rec.start
sleep 30.seconds
rec.stop
System audio capture requires:
require "crystal_audio"
rec = CrystalAudio::Recorder.new(
source: CrystalAudio::RecordingSource::Both,
output_path: "/tmp/meeting.wav", # System audio
mic_output_path: "/tmp/dictation.wav" # Microphone
)
rec.start
sleep 60.seconds
rec.stop
| Source | Description | macOS Version | Permission |
|---|---|---|---|
Microphone | Mic input via AudioQueue | 13.0+ | Microphone |
System | What the computer plays, via ProcessTap or SCStream | 13.0+ | None (14.2+) or Screen Recording (13.x) |
Both | Mic + system simultaneously, two output files | 13.0+ | Both above |
For apps that access system audio or microphone, create an Info.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>NSMicrophoneUsageDescription</key>
<string>Record audio from the microphone</string>
<key>NSAudioCaptureUsageDescription</key>
<string>Capture system audio output</string>
</dict>
</plist>
Recordings are saved as WAV files:
If working directly with the crystal-audio source:
make ext # Compile C/ObjC extensions
make record # Build CLI recorder sample
make macos-app # Build macOS desktop GUI app
make ios-app # Build iOS Simulator app (requires crystal-alpha + xcodegen)
make spec # Run test suite
make clean # Remove build artifacts
crystal-audio bridges Crystal to Apple's audio frameworks via:
objc_msgSend)objc_msgSend variants and ObjC block constructionThe library detects macOS version at runtime and selects the optimal audio capture path automatically.
Cross-compile Crystal code as a static library for iOS and link it into a Swift app. Covers the complete pipeline: cross-compilation, runtime initialization, Xcode project setup, and critical linker configuration. Documents hard-won solutions to dead-stripping, symbol conflicts, and simulator deployment issues.
Record audio from the microphone using crystal-audio's Recorder class. Covers AudioQueue configuration, WAV output, buffer management, and real-time audio callback patterns. Use this when implementing mic recording features in Crystal.
Capture system audio (what the computer is playing) using crystal-audio. Covers ProcessTap (macOS 14.2+), ScreenCaptureKit fallback (macOS 13.0+), and the low-level SystemAudioCapture API for real-time audio processing.