<h1 align="center">OpenSuperMLX</h1>
<p align="center">
<b>사용자의 Mac을 위한 개인 정보 보호 실시간 받아쓰기 기능입니다.</b><br />어떤 앱에서든 단축키를 누르고 말하면 타이핑하는 위치에 단어가 나타납니다.<br />Mac에서 전사되며, 절대 업로드되지 않습니다.
</p>
<p align="center">
<a href="https://github.com/axot/OpenSuperMLX/releases/latest"><img src="https://img.shields.io/github/v/release/axot/OpenSuperMLX?label=release&color=0A0A0A" alt="Latest release" /></a>
<img src="https://img.shields.io/badge/macOS-15%2B-0A0A0A" alt="macOS 15 or later" />
<img src="https://img.shields.io/badge/Apple%20Silicon-only-0A0A0A" alt="Apple Silicon only" />
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0A0A0A" alt="MIT license" /></a>
</p>
<p align="center">
<code >brew tap axot/tap && brew install --cask opensupermlx</code><br />
또는 <a href="https://github.com/axot/OpenSuperMLX/releases/latest">최신 릴리스</a>에서 DMG 파일을 다운로드하세요.
</p>
<p align="center">
<img src="https://raw.githubusercontent.com/axot/OpenSuperMLX/HEAD/docs/preview.png" alt="OpenSuperMLX recordings and stats views with synthetic transcript history and activity dashboard" width="920" />
</p>
작동 방식 (How it works)
- 어떤 앱에서든 <kbd>⌥</kbd> + <kbd>`</kbd>를 누르거나 말하는 동안 길게 누릅니다.
- 말합니다. 텍스트가 실시간으로 나타납니다.
- 멈추면, 전사된 내용이 커서 위치에 붙여넣어집니다.
왜 OpenSuperMLX인가 (Why OpenSuperMLX)
- 개인 정보 보호 설계 (Private by design). 음성 인식은 Mac에서만 완전히 실행되며, [MLX]와 Neural Engine을 사용하여 Qwen3-ASR을 구동합니다. 계정이나 구독이 필요 없으며, 오디오는 어딘가로 전송되지 않습니다.
- 입력하는 모든 곳에서 작동합니다. Slack, 이메일, 문서, 에디터, AI 채팅 상자 등: 하나의 전역 단축키만으로 사용 중인 앱에 텍스트를 입력할 수 있습니다.
- 장시간 세션에서도 실시간입니다. 말하는 동안 단어가 스트리밍되며, 긴 회의도 계속해서 전사(transcribing)됩니다.
- 다국어 사용자에게 최적화되었습니다. 19개 언어에 걸쳐 자동으로 언어를 감지하고, 중국어, 일본어, 한국어의 공백과 구두점을 수정하며, 숫자도 중국어와 영어에서 숫자로 작성합니다.
- 다시 돌아올 수 있는 녹음 기록. 모든 세션은 오디오와 함께 검색 가능한 기록으로 보관됩니다. 저장에 실패하더라도 녹음을 잃는 대신 다시 시도할 수 있습니다. 기존 오디오 파일을 넣어 전사(transcribe)할 수도 있습니다.
- 선택적 LLM 정리 (cleanup). 두 번째 단축키를 사용하면 오직 텍스트만 사용자의 자체 AWS Bedrock 또는 OpenAI 호환 모델로 보내 잘못 들은 단어와 구두점을 수정합니다.
활용 분야 (Made for)
- 작문 속도 향상: 회의록, 채팅 답장, 프롬프트, 문서 및 후속 조치 작성에 활용합니다.
- 회의 및 통화: 헤드폰을 착용하면 OpenSuperMLX가 사용자의 마이크와 통화 상대방의 소리를 함께 녹음할 수 있습니다.
- 개발자 및 AI 에이전트: 로컬 MCP 서버를 통해 에이전트가 실시간 전사본을 목록화하고, 검색하며, 추적할 수 있으며, CLI는 전사(transcription), 벤치마크(benchmarks), 진단 기능을 제공합니다.
기능 (Features)
음성 받아쓰기 (Dictation)
- 단축키를 탭하여 시작 및 중지하거나, 누르고 있는 동안만 녹음하려면 길게 누릅니다. 취소하려면 <kbd>Escape</kbd> 키를 누르세요.
- 실시간 스트리밍 전사(transcription).
- 내장형, USB, 블루투스 및 Continuity 마이크 간 전환이 가능합니다.
- 헤드폰 사용 시 선택적 시스템 오디오 캡처가 가능합니다. 스피커에서는 에코를 방지하기 위해 마이크만 녹음합니다.
텍스트 기능
- 자동 언어 감지 또는 19개 언어 중 하나를 선택할 수 있습니다.
- 중국어, 일본어, 한국어를 위한 아시아권 맞춤법 검사기(autocorrect).
- 중국어와 영어의 숫자, 날짜 및 금액을 숫자로 표기 (역 텍스트 정규화, inverse text normalization) 기능.
- AWS Bedrock 또는 모든 OpenAI 호환 API를 통한 선택적 대규모 언어 모델(LLM) 교정 기능. 긴 전사본은 모델 제한에 맞게 분할됩니다.
기록 및 통계
- 검색 가능한 전사 기록을 제공합니다. 오디오에서 전사본을 재생성할 수 있습니다.
- 녹음은 48kbps의 16kHz 모노 AAC로 저장됩니다. 가져온 오디오는 원래 형식을 유지합니다.
- 오디오 파일을 드래그 앤 드롭하여 대기열(queue)에 넣고 전사할 수 있습니다.
- 세션, 연속 기록(streaks), 말한 시간, 타이핑 대비 절약된 시간을 보여주는 통계 대시보드(stats dashboard).
신뢰성
- 녹음을 저장할 수 없는 경우, 복구 패널(recovery panel)을 통해 재시도하거나, 전사본을 복사하거나, 폐기할 수 있습니다.
- Apple Developer ID로 서명되었으며 Apple에 의해 공증되었습니다.
- 녹음이 끝날 때까지 기다리는 자동 업데이트 기능입니다.
개발자용 기능
- 헤드리스(headless) 명령줄 인터페이스(CLI):
transcribe, stream-simulate, correct, config, recordings, queue, mic, model, benchmark, diagnose가 포함됩니다.
- 에이전트가 실시간 전사본에 접근할 수 있도록
127.0.0.1에서 선택적(opt-in) 전사 MCP 서버를 제공합니다.
설치
Homebrew
brew tap axot/tap
brew install --cask opensupermlx
다운로드
[최신 릴리스]에서 DMG 파일을 다운로드하고, 열어 OpenSuperMLX를 응용 프로그램(Applications) 폴더로 드래그합니다.
권한 설정
처음 실행 시, macOS는 마이크 및 접근성(accessibility) 권한을 요청합니다. OpenSuperMLX는 녹음을 위한 마이크와 다른 앱에 텍스트를 붙여넣기 위한 접근성 기능, 두 가지 모두가 필요합니다. 시스템 오디오를 캡처하려면 화면 기록(Screen Recording) 권한도 필요합니다.
업데이트
OpenSuperMLX는 매일 한 번 GitHub 릴리스를 확인합니다. 지금 바로 확인하려면 왼쪽 상단 애플리케이션 메뉴에서 **OpenSuperMLX → 업데이트 확인(Check for Updates…)**을 선택하거나, **설정(Settings) → 고급(Advanced) → 업데이트(Updates) → 지금 확인(Check now)**을 선택하세요. **업데이트 확인…**은 메뉴 막대 아이콘에서도 사용할 수 있습니다.
예약된 업데이트 알림은 녹음을 마치고 타이핑을 멈출 때까지 기다립니다. 업데이트 요청 재시작은 녹음, 저장 또는 전사되는 것이 없을 때까지 기다립니다. 업데이트 창에서 자동 다운로드 및 설치를 활성화하면 백그라운드에서 업데이트가 준비되어 앱을 종료할 때 설치될 수 있습니다. 자동 확인 기능을 비활성화하려면 **설정(Settings) → 고급(Advanced) → 업데이트(Updates) → 자동으로 업데이트 확인(Check for updates automatically)**을 끄십시오.
버전 0.1.1 이전 버전은 스스로 업데이트할 수 없습니다: 릴리스 페이지에서 다음 릴리스를 한 번 설치하거나 brew upgrade --cask opensupermlx 명령어를 사용하십시오. Homebrew 설치는 이전에처럼 brew upgrade로 계속 작동합니다.
요구 사항 (Requirements)
- macOS 15 이상
- Apple Silicon이 탑재된 Mac
모델 (Model)
OpenSuperMLX는 기본적으로 Qwen3-ASR-1.7B-5bit (약 1.8 GB)를 사용하며, 이는 첫 실행 설정 시 Hugging Face에서 다운로드됩니다.
**설정(Settings) → 모델(Model)**에는 ~/Library/Application Support/org.axot.OpenSuperMLX/mlx-models/mlx-audio에 있는 모든 모델 폴더가 나열됩니다. MLX 모델을 추가하려면 해당 Hugging Face 폴더를 <org>_<name> 형식(예: mlx-community_nemotron-3.5-asr-streaming-0.6b-8bit)으로 복사한 다음 선택하십시오. 지원되는 모델 유형은 다음과 같습니다:
model_type | 예시 (Example) | 스트리밍 방식 (Streaming) |
|---|
qwen3_asr | mlx-community/Qwen3-ASR-1.7B-5bit | 녹음 중 실시간 전사 (Live while recording) |
nemotron_asr | mlx-community/nemotron-3.5-asr-streaming-0.6b-8bit | 녹음 정지 시 전사 (Transcribes when recording stops) |
다른 모델 유형을 가진 폴더는 지원되지 않음으로 표시됩니다.
설정(Settings) → 모델(Model) → Neural Engine 오디오 인코더 (기본 활성화됨)는 모델의 오디오 인코더를 GPU 대신 Neural Engine에서 실행합니다. 모델이 처음 로드될 때 앱은 인코더의 Core ML 버전을 다운로드합니다 (약 300 MB). 이 설정을 끄면 대신 GPU 인코더를 사용하게 됩니다. Core ML 인코더는 Qwen3-ASR-1.7B에서 변환되었기 때문에, Qwen3-ASR-0.6B와 같은 다른 모델은 항상 인코더를 GPU에서 실행합니다.
단축키 (Shortcuts)
| 단축키(Shortcut) | 동작(Action) |
|---|
| Option(⌥) + Command(⌘) | 녹음 시작 또는 중지 |
| ... | ... |
| 단축키는 **설정(Settings) → 단축키(Shortcuts)**에서 변경하세요. | |
CLI (명령줄 인터페이스)
앱 바이너리(binary)는 헤드리스 CLI로도 사용됩니다:
BINARY=build/Build/Products/Debug/OpenSuperMLX.app/Contents/MacOS/OpenSuperMLX
$BINARY diagnose --json
$BINARY help transcribe
전체 명령어 참조는 docs/cli.md를 확인하세요.
소스 코드에서 빌드하기 (Build from source)
git clone [email protected]:axot/OpenSuperMLX.git
cd OpenSuperMLX
git submodule update --init --recursive
...
첫 빌드 후에는 Swift 전용 변경 사항에 대해 AGENTS.md의 더 빠른 증분(incremental) xcodebuild 명령을 사용할 수 있습니다. ./run.sh는 모든 네이티브 컴포넌트를 재빌드하고 앱을 실행하며, ./run.sh build는 실행 없이 빌드를 수행합니다.
지원 (Support)
문제가 발생하면:
- 기존 GitHub 이슈를 검색하세요.
- CLI에서
diagnose --json을 실행하고 docs/logging.md에 설명된 대로 관련 로그를 수집하세요.
- 재현 단계와 진단 출력을 포함하여 새 이슈를 여세요.
만약 녹음 저장 안됨(Recording Not Saved) 패널이 나타나면, 디스크 공간을 확보하거나 스토리지 문제를 해결한 다음 **재시도(Retry)**를 선택하세요. **전사본 복사(Copy Transcript)**는 텍스트를 클립보드에 넣습니다. **저장 취소(Cancel Save)**는 확인 요청 후 오디오와 전사본을 영구적으로 폐기합니다. 녹음 분석 및 복구에 대한 자세한 내용은 docs/audio-diagnostics.md를 참조하세요.
감사의 말씀 (Acknowledgments)
OpenSuperMLX는 @Starmel의 OpenSuperWhisper에서 포크되었습니다. 기반이 된 원본 프로젝트에 감사드립니다.
라이선스 (License)
OpenSuperMLX는 MIT 라이선스(MIT License) 하에 배포됩니다. 자세한 내용은 LICENSE를 참조하세요.
