Bắt đầu

Cài CLI speech để chuyển âm thanh thành văn bản và tạo giọng nói trên máy Mac dùng Apple Silicon. Dùng Swift SDK để thêm tính năng xử lý giọng nói vào ứng dụng macOS và iOS.

Yêu cầu của CLI

• macOS 15+ (Sequoia trở lên)
• Apple Silicon (arm64)
• Tối thiểu 8 GB RAM (khuyến nghị 16 GB cho các mô hình lớn hơn)

Cài đặt CLI

Homebrew (CLI)

Dùng Homebrew bản ARM gốc (/opt/homebrew) để cài speech và máy chủ HTTP/WebSocket speech-server.

brew install speech
speech --help

Tác vụ đầu tiên: chuyển tệp M4A thành văn bản

Tải bản ghi âm mẫu, rồi chuyển thành văn bản trong terminal:

Kết nối internet khi chạy lần đầu. Mô hình đã chọn sẽ được tải từ HuggingFace và lưu trong bộ nhớ đệm trên máy Mac. Sau khi thiết lập, bạn có thể dùng mô hình đó để xử lý bản ghi âm cục bộ mà không cần internet.

curl -fL https://soniqo.audio/audio/samples/cli/transcription-sample.m4a -o transcription-sample.m4a
speech transcribe transcription-sample.m4a --engine parakeet

Xem tiếp hướng dẫn chuyển M4A thành văn bản.

Khởi động nhanh: văn bản thành giọng nói

speech speak "Hello, world!" --output hello.wav

Chạy API giọng nói cục bộ

Khởi động máy chủ HTTP/WebSocket để xử lý các yêu cầu API cục bộ:

speech-server --port 8080

Swift SDK

Thêm các mô-đun Swift vào ứng dụng macOS 15+ hoặc iOS 18+ bằng Swift Package Manager.

Swift Package Manager

Thêm speech-swift vào các phụ thuộc trong Package.swift của bạn:

dependencies: [
    .package(url: "https://github.com/soniqo/speech-swift", branch: "main")
]

Sau đó thêm các module bạn cần vào target:

.target(
    name: "MyApp",
    dependencies: [
        .product(name: "Qwen3ASR", package: "speech-swift"),
        .product(name: "Qwen3TTS", package: "speech-swift"),
        .product(name: "SpeechVAD", package: "speech-swift"),
        // ... add any modules you need
    ]
)

Các module có sẵn

Chuyển âm thanh thành văn bản bằng Swift

import Qwen3ASR

let model = try await Qwen3ASRModel.fromPretrained()
// audioSamples: [Float] PCM at 16 kHz (e.g. decoded from a WAV)
let text = model.transcribe(audio: audioSamples, sampleRate: 16000)
print(text)

Tạo giọng nói bằng Swift

import Qwen3TTS
import AudioCommon

let model = try await Qwen3TTSModel.fromPretrained()
let audio = model.synthesize(text: "Hello, world!", language: "english")
try WAVWriter.write(samples: audio, sampleRate: 24000, to: URL(filePath: "hello.wav"))

Biên dịch từ mã nguồn

Để biên dịch từ mã nguồn, hãy cài Xcode 16.3+ có Metal Toolchain và Swift 6+. Sao chép kho mã, biên dịch CLI, rồi kiểm tra tệp thực thi trong thư mục mã nguồn:

git clone https://github.com/soniqo/speech-swift.git
cd speech-swift
make build
.build/release/speech --help

Shader mặc định được biên dịch cho macOS 15.0 và Metal 3.2, ngay cả với SDK mới hơn. Với bản dựng tùy chỉnh, MACOSX_DEPLOYMENT_TARGET và MLX_METAL_LANGUAGE_VERSION thay đổi các giá trị này; phiên bản đích cao hơn có thể không hỗ trợ hệ thống cũ. Thay đổi trình biên dịch, SDK, cờ, tập lệnh hoặc mã nguồn sẽ làm mất hiệu lực bộ nhớ đệm. Khi biên dịch hoặc liên kết thất bại, thư viện và mã băm bộ nhớ đệm trước đó được giữ nguyên.

Tải mô hình

Các mô hình được tải tự động từ HuggingFace ở lần dùng đầu tiên và lưu trong ~/Library/Caches/qwen3-speech/.

Tất cả các mô hình đều được tải từ HuggingFace ở lần dùng đầu tiên. Kích thước ước tính:

Bước tiếp theo

• Xem tiếp hướng dẫn chuyển M4A thành văn bản
• Tham khảo CLI — tất cả các lệnh và tùy chọn có sẵn
• Hướng dẫn Qwen3-ASR — tài liệu chi tiết về chuyển giọng nói thành văn bản
• Hướng dẫn Qwen3-TTS — tài liệu chi tiết về văn bản thành giọng nói
• API và giao thức — các giao thức và kiểu dữ liệu dùng chung