라이트온 AI 노트는 강의나 설교를 녹음하면서 실시간으로 받아 적는 앱입니다. 1.2.7 버전으로 30분 분량의 설교를 안드로이드에서 녹음해 본 테스트에서 두 가지 보고가 올라왔습니다.
- "전사 중에 화면이 멈춰 있다. 업데이트하면서 자동 스크롤이 빠진 것 같다."
- "30분쯤 지나면 이상한 언어가 잠깐 전사된다."
따라가 보니 원인은 셋이었고, 어느 것도 코드가 빠져서 생긴 일이 아니었습니다. 자동 스크롤을 켜고 끄는 조건, 전사 엔진이 내려 준 확정 텍스트를 앱이 붙잡아 두는 규칙, 언어 자동 감지 설정입니다. 실시간 전사 화면을 만든다면 한 번쯤 밟을 자리라서 진단과 수정 과정을 그대로 적어 둡니다.
먼저 의심한 것들, 그리고 아니었던 이유
자동 스크롤 코드가 빠졌나? git 이력을 보니 한 달 전에 넣은 "받아쓰는 동안 문서 끝을 따라가는" 코드는 그대로 있었습니다. 있는데 동작하지 않는 상황이었습니다.
30분짜리 타이머가 있나? "30분쯤"이라는 단서가 구체적이어서 시간에 걸린 로직부터 찾았습니다. 앱 코드에는 30분에 반응하는 타이머가 없었고, 전사 엔진인 Soniox도 공식 문서상 실시간 세션 상한이 300분입니다. 시간이 아니라면 그 무렵 마이크로 들어온 소리를 의심해야 합니다.
재현 환경: iOS 시뮬레이터와 macOS say
보고는 안드로이드에서 왔지만 스크롤과 확정 로직은 모두 Dart 코드라 플랫폼을 타지 않습니다. 그래서 맥에서 바로 띄우는 iOS 시뮬레이터로 재현했습니다.
마이크 기능은 사람이 직접 말해야 검증되니 자꾸 뒤로 밀립니다. 그래서 맥이 말하게 했습니다. macOS say로 한국어 원고를 읽히면 맥 스피커의 소리가 맥 마이크로 들어가고, 시뮬레이터는 맥의 오디오 입력을 마이크로 씁니다. 녹음 버튼만 눌러 두면 같은 원고를 몇 번이든 같은 조건으로 흘려 넣을 수 있습니다.
# 1) 시뮬레이터용 디버그 빌드 → 설치 → 실행
flutter build ios --simulator --debug --dart-define-from-file=<환경 파일>
xcrun simctl install $UDID build/ios/iphonesimulator/Runner.app
xcrun simctl launch $UDID <번들 ID>
# 2) 앱에서 녹음을 시작한 뒤, 맥이 원고를 읽게 한다 (Yuna = macOS 한국어 음성)
say -v Yuna -r 170 -f sermon.txt
# "쉬지 않는 화자" 만들기: 마침표와 줄바꿈을 지워 문장 사이 쉼을 줄인다
tr -d '.\n' < sermon.txt > sermon_nopause.txt
say -v Yuna -r 175 -f sermon_nopause.txt
# 3) 앱 로그에서 확정 발화만 뽑는다
xcrun simctl spawn $UDID log show --last 2m \
--predicate 'process == "Runner"' --style compact \
| grep -E '\[SonioxStream\] (FINAL|dropping)'
판단은 로그로 했습니다. 앱은 확정 발화마다 오디오 구간(초)과 텍스트를 한 줄로 남깁니다.
[SonioxStream] FINAL spk=null→A lang=ko [1.26..8.64] "…"
이 구간 숫자만 모으면 확정이 몇 초 간격으로 들어오는지 보입니다. 스크린샷으로는 "멈춘 것 같다"까지만 알 수 있지만, 로그로는 멈춘 게 스크롤인지 데이터인지를 가를 수 있습니다.
단, 테스트하던 맥에서 뉴스 영상 소리가 함께 재생되고 있어 마이크에는 낭독과 뉴스 음성이 겹쳐 들어갔습니다. 이 환경으로 전사 품질은 평가할 수 없지만, "언제 확정되는가, 화면이 따라가는가"라는 동작을 보기에는 충분했고 배경 소리가 깔리는 현장과 오히려 비슷했습니다.
원인 1 — 팔로우 조건이 캐럿 위치에 묶여 있었다
편집 화면은 바깥 SingleChildScrollView 안에 maxLines: null인 본문 TextField가 있고, 그 아래에 회색 임시 자막 줄이 붙는 구조입니다. 여기서는 컨트롤러로 캐럿을 끝에 옮겨도 화면이 따라 내려가지 않아서, 확정 문장을 삽입한 뒤 바깥 스크롤을 직접 끝으로 점프시키게 했습니다. 문제는 점프 여부를 정하는 조건이었습니다.
// 수정 전: 확정 발화를 본문 끝에 붙일 때 (실제 코드 발췌)
final oldSel = _contentController.selection;
final caretFollowingEnd = !oldSel.isValid ||
(oldSel.isCollapsed && oldSel.baseOffset >= currentText.length);
newSelection = caretFollowingEnd
? TextSelection.collapsed(offset: newText.length)
: oldSel; // 캐럿이 끝이 아니면 그 자리에 둔다
followToEnd = caretFollowingEnd;
의도는 좋았습니다. 문서 중간에서 오타를 고치는 사람을 새 문장이 들어올 때마다 끝으로 끌어내리면 방해가 됩니다. 그래서 "캐럿이 끝에 있다"를 "따라가며 보고 있다"로 해석했습니다.
그런데 이 조건은 한 번 꺼지면 다시 켜지지 않습니다. 캐럿이 끝에 없으면 선택 영역을 그대로 두고 새 텍스트는 문서 끝에 붙으니, 캐럿은 점점 끝에서 멀어지고 조건은 계속 거짓으로 남습니다. 사용자가 직접 캐럿을 맨 끝으로 옮기기 전까지 그 녹음 내내 팔로우가 꺼집니다.
캐럿이 끝에서 떨어지는 일도 흔했습니다. 본문을 한 번 탭하면 충분하고, 화면이 잠겼다 풀릴 때 키보드(IME)가 예전 입력 상태를 되돌려 주면서 캐럿이 옮겨지기도 합니다. 설교를 녹음하며 폰을 잠그는 건 평범한 사용인데, 아무것도 편집하지 않은 사용자를 앱은 "편집 중"으로 보고 있었습니다.
원인 2 — 휴지(<end>)가 와야만 확정했다
캐럿을 건드리지 않았는데도 쉬지 않고 읽히면 화면이 멈춘 것처럼 보였습니다. 확정 규칙을 고치기 전 빌드의 로그가 이유를 보여 줬습니다. 녹음을 시작하고 약 10초 뒤 확정 한 줄([1.26..8.64])이 찍힌 다음, 1초마다 찍히는 오디오 전송량 로그가 180초 가까이 올라가는 동안 확정 로그가 한 줄도 추가되지 않았습니다. 오디오는 계속 올라가는데 확정만 내려오지 않았습니다.
Soniox 실시간 API는 토큰을 두 종류로 보냅니다. 확정 전(non-final) 토큰은 바로 나타나지만 오디오가 더 들어오면 바뀌거나 사라질 수 있고, 확정(final) 토큰은 한 번 확정되면 다시 바뀌지 않습니다. 엔드포인트 감지(enable_endpoint_detection)를 켜면 말이 끝났다고 판단한 지점에서 구간을 확정하고 <end>라는 특별한 토큰을 보냅니다.
앱은 그 위에 한 겹을 더 두고 있었습니다. 확정 토큰도 바로 본문에 넣지 않고 버퍼에 모았다가, <end>가 오면 한 발화로 묶어 내보냈습니다. 앱에서 발화 한 건은 화자 라벨, 언어, 시간 구간, 오디오 조각이 함께 묶이는 단위라 휴지로 끊는 설계 자체는 합리적이었습니다. 버퍼의 확정 토큰과 확정 전 꼬리는 합쳐서 회색 임시 줄로 보여 줬습니다.
문제는 <end>가 휴지에 달려 있다는 점입니다. 설교자가 쉬지 않고 말하거나 배경 음악, 다른 목소리가 계속 깔리면 휴지가 감지되지 않고, 확정 토큰은 버퍼에 몇 분씩 쌓입니다. 자동 스크롤은 본문 삽입 때만 움직였으니 화면도 그대로이고, 회색 임시 줄은 화면 아래 보이지 않는 곳에서 길어집니다. 사용자 눈에는 정확히 "화면이 멈춘 것"입니다.
Soniox의 max_endpoint_delay_ms 같은 파라미터는 문서상 말이 끝난 뒤 엔드포인트를 얼마나 빨리 돌려줄지를 정하므로, 말이 끝나지 않는 상황에는 소용이 없습니다. 게다가 토큰은 이미 확정 상태로 와 있었고 붙잡고 있던 건 앱이었습니다. 고칠 곳은 앱의 버퍼 규칙이었습니다.
원인 3 — 언어 힌트는 제한이 아니었다
음성 인식 언어가 기본값 "자동"일 때 앱이 보내던 설정입니다.
// 수정 전: 언어 설정이 "자동"일 때의 요청 일부
'language_hints': ['ko', 'en', 'zh', 'ja'],
'enable_language_identification': true,
'enable_endpoint_detection': true,
// language_hints_strict 없음
Soniox 문서는 언어 힌트를 분명하게 설명합니다. 힌트는 인식을 그 언어들 쪽으로 기울일 뿐, 그 언어로 제한하지 않습니다. Soniox는 60개가 넘는 언어를 인식하므로 힌트 밖의 언어도 나올 수 있습니다. 평소 한국어는 한국어로 잘 나오지만, 소음이나 음악이 섞이거나 마이크가 다시 시작된 직후처럼 오디오가 애매한 구간은 다른 언어로 판정될 수 있고, 그러면 그 언어의 문자로 그럴듯한 문장이 몇 초 찍힙니다. "30분쯤"은 그런 구간이 마침 그 무렵에 있었다는 뜻이었지, 30분이라는 시간에 의미가 있던 게 아니었습니다.
수정 1 — 팔로우를 스크롤 위치로 판단한다
캐럿은 사용자의 의도를 대신 알려 주는 지표로 너무 약했습니다. 의도가 직접 드러나는 신호는 따로 있습니다. 손가락으로 화면을 끌어 올렸는가입니다.
// 실제 코드 발췌. 한국어 주석은 설명을 위해 덧붙였습니다.
static const double _followSlackPx = 48; // 본문 아래 여백은 200px
bool _onContentScroll(ScrollNotification n) {
if (n.depth != 0) return false; // 안쪽 뷰포트에서 올라온 알림은 무시
final m = n.metrics;
if (!m.hasContentDimensions) return false;
final atBottom = m.pixels >= m.maxScrollExtent - _followSlackPx;
if (n is ScrollUpdateNotification && n.dragDetails != null) {
_userScrolledAway = !atBottom; // 손가락으로 끌었을 때만 판단
} else if (n is ScrollEndNotification && atBottom) {
_userScrolledAway = false; // 바닥에서 멈추면 다시 따라간다
}
return false;
}
핵심은 dragDetails입니다. Flutter 문서에 따르면 ScrollUpdateNotification.dragDetails는 드래그 때문에 스크롤 위치가 바뀌었을 때만 채워지고, 그 밖에는 null입니다. 그래서 앱이 jumpTo로 내려간 것을 사용자의 스크롤로 오인하지 않습니다. 위로 끌어 올리면 팔로우를 멈추고, 스크롤이 바닥 근처에서 멈추면 다시 켭니다. 본문 아래 여백이 200px이라 48px 정도 어긋나도 가려지는 글은 없습니다.
캐럿을 아예 무시하지는 않았습니다. 대신 "최근에 사용자가 직접 만졌는가"라는 조건을 붙였습니다.
DateTime? _lastEditorTouchAt; // 탭·타이핑·포커스 때 갱신
static const Duration _editingGrace = Duration(seconds: 45);
bool get _recentlyEditing =>
_lastEditorTouchAt != null &&
DateTime.now().difference(_lastEditorTouchAt!) < _editingGrace;
// 수정 후: 확정 발화를 본문 끝에 붙일 때
final caretAtEnd = !oldSel.isValid ||
(oldSel.isCollapsed && oldSel.baseOffset >= currentText.length);
final editingElsewhere = !caretAtEnd && _recentlyEditing;
newSelection = editingElsewhere
? oldSel
: TextSelection.collapsed(offset: newText.length);
followToEnd = !editingElsewhere && !_painting && !_userScrolledAway;
탭, 타이핑, 포커스 시각을 기록해 두고 그로부터 45초 안에서만 중간의 캐럿을 "편집 중"으로 봅니다. 그 밖이라면 떠밀린 캐럿이니 끝으로 옮기고 계속 따라갑니다. 오타를 고친 뒤 45초가 지나면 저절로 다시 따라가므로 영영 꺼지는 일이 없습니다. _painting은 형광펜 모드로, 이때는 따라가지 않습니다.
회색 임시 줄도 따라가게 했습니다. 그래야 원인 2 같은 상황에서도 화면이 움직입니다. 새 녹음을 시작하면 위로 올려 둔 상태도 초기화합니다.
ref.listen<SpeechState>(speechProvider, (previous, next) {
// 새 녹음은 항상 따라가는 상태로 시작한다
if (next.isListening && previous?.isListening != true) {
_userScrolledAway = false;
}
// 회색 임시 줄이 바뀔 때도 끝으로 내린다
if (next.currentText.isNotEmpty &&
next.currentText != previous?.currentText &&
_followingTranscript()) {
_scrollTranscriptToEnd();
}
// ... 확정 발화 삽입 처리
});
void _scrollTranscriptToEnd() {
WidgetsBinding.instance.addPostFrameCallback((_) {
if (!mounted || !_contentScrollController.hasClients) return;
final max = _contentScrollController.position.maxScrollExtent;
if (_contentScrollController.offset >= max) return;
_contentScrollController.jumpTo(max);
});
}
스크롤은 기존대로 다음 프레임에 maxScrollExtent로 점프합니다. 프레임이 끝나야 새 텍스트 높이가 반영되고, 전사 조각은 애니메이션이 끝나기 전에 다음 것이 들어와서 animateTo를 쓰면 애니메이션끼리 겹칩니다.
수정 2 — 휴지가 오지 않아도 확정한다
버퍼에 상한을 두었습니다. 쌓인 확정 토큰이 오디오 시간으로 12초를 넘기면, 12초 지점을 지난 마지막 문장 끝(. ! ? 。 등)에서 잘라 그 앞까지를 한 발화로 내보냅니다. 문장부호가 전혀 없으면 30초에서 무조건 내보냅니다. 자른 지점 뒤의 토큰은 버퍼에 그대로 남아 다음 휴지나 다음 조기 확정 때 함께 나갑니다.
// 실제 코드 발췌 (Soniox 스트리밍 서비스)
static const int _softFlushAfterMs = 12000;
static const int _hardFlushAfterMs = 30000;
static final RegExp _sentenceEnd = RegExp(r'[.!?。!?]\s*$');
bool _flushEarlyIfDue() {
if (_pendingFinals.isEmpty) return false;
final first = _startOf(_pendingFinals.first);
final span = _endOf(_pendingFinals.last) - first; // 오디오 시간(ms)
if (span < _softFlushAfterMs) return false;
var cut = -1;
for (var i = _pendingFinals.length - 1; i >= 0; i--) {
final t = _pendingFinals[i];
if (!_sentenceEnd.hasMatch((t['text'] as String?) ?? '')) continue;
if (_endOf(t) - first >= _softFlushAfterMs) cut = i;
break; // 마지막 문장 끝만 후보
}
if (cut < 0) {
if (span < _hardFlushAfterMs) return false;
cut = _pendingFinals.length - 1; // 30초: 전부 내보낸다
}
final tail = _pendingFinals.sublist(cut + 1);
_pendingFinals.removeRange(cut + 1, _pendingFinals.length);
_flushUtterance(keepSeenFinals: true);
_pendingFinals.addAll(tail); // 자른 뒤는 계속 보류
return true;
}
// 메시지 처리부 (분기를 합쳐 요약)
if (sawEnd) {
_flushUtterance(); // 휴지: 버퍼 전체를 한 발화로
} else {
_flushEarlyIfDue(); // 휴지가 없어도 상한을 넘겼으면 일부 확정
// 남은 확정 토큰 + 확정 전 꼬리 = 회색 임시 줄
_maybeEmitInterim(
_pendingFinals.map((t) => t['text']).join() + newInterimParts.join(),
);
}
기준은 벽시계가 아니라 토큰의 start_ms/end_ms, 즉 오디오 시간입니다. 네트워크가 느려도 같은 오디오에는 같은 결과가 나오고, 소켓 없이 메시지만 흘려 넣는 테스트로 규칙을 검증할 수 있습니다.
첫 구현은 버퍼의 맨 마지막 토큰이 문장부호로 끝날 때만 12초 조건으로 잘랐습니다. 이 버전에 쉼을 줄인 원고를 흘리자 로그에 [21.72..53.28], 31초가 넘는 발화가 한 덩어리로 찍혔습니다. 30초 강제 확정은 동작했지만, 그 31초 동안 문장 끝 조건은 한 번도 맞지 않았다는 뜻입니다. 메시지는 문장 경계에 맞춰 끊겨 오지 않으니, 도착한 순간 마지막 토큰이 마침표로 끝나 있을 가능성은 낮습니다. 그래서 버퍼를 뒤에서부터 훑어 마지막 문장 끝에서 자르도록 바꿨습니다.
놓치기 쉬운 부분도 있습니다. 기존 코드는 같은 start_ms의 확정 토큰이 인접 메시지에서 다시 들어오는 경우를 막으려고 본 시작 시각을 집합에 들고 있다가 발화를 내보낼 때마다 비웠습니다. 조기 확정은 말하는 도중에 자르는 것이라 여기서 비우면 중복 방어가 풀리므로 keepSeenFinals: true로 유지합니다.
수정 3 — strict 힌트와 문자 체계 가드
요청에 language_hints_strict를 추가했습니다.
'language_hints': hints,
'language_hints_strict': true,
'enable_language_identification': true,
'enable_endpoint_detection': true,
Soniox 문서는 이 옵션을 켜면 모델이 지정한 언어로만 출력하는 쪽을 강하게 선호한다고 설명하면서, 최선 노력일 뿐 보장은 아니며 언어를 하나만 지정했을 때 가장 견고하다고 적어 둡니다. 자동 모드는 언어를 넷 지정하니 strict만 믿을 수는 없었습니다.
그래서 앱 쪽에 방어선을 하나 더 두었습니다. 확정 발화를 내보내기 직전에 글자마다 문자 체계(한글, 라틴, 가나, 한자, 그 밖)를 판별하고, 힌트 언어들이 쓰지 않는 문자가 절반 이상이면 그 발화를 버립니다.
// 실제 코드 발췌 (문자 체계 가드)
static const double dropRatio = 0.5;
static bool isOutsideHints(String text, List<String> hints) {
if (hints.isEmpty) return false;
final allowed = <_Script>{_Script.latin}; // 라틴은 항상 허용
for (final h in hints) {
final s = _scriptsFor(h.toLowerCase());
if (s == null) return false; // 모르는 언어면 가드 해제
allowed.addAll(s);
}
var letters = 0;
var foreign = 0;
for (final rune in text.runes) {
final script = _classify(rune);
if (script == null) continue; // 숫자·문장부호·공백
letters++;
if (!allowed.contains(script)) foreign++;
}
if (letters == 0) return false;
return foreign / letters >= dropRatio;
}
static Set<_Script>? _scriptsFor(String code) => switch (code) {
'ko' => const {_Script.hangul},
'en' => const {_Script.latin},
'ja' => const {_Script.kana, _Script.han},
'zh' => const {_Script.han},
_ => null,
};
규칙을 정하면서 고민한 지점은 셋입니다.
- 라틴 문자는 항상 허용합니다. 한국어 강의에도 "AI", "GPT" 같은 용어가 계속 나옵니다.
- 숫자, 문장부호, 공백은 세지 않습니다. "3:16" 같은 장절 표기만 있는 발화가 버려지면 안 됩니다.
- 모르는 언어 코드가 힌트에 있으면 가드를 끕니다. 어떤 문자를 쓰는지 모르면서 버리느니 두는 편이 안전합니다.
한계도 분명합니다. 자동 모드에서는 가나와 한자가 허용되므로, 한국어를 일본어로 잘못 판정한 출력은 그대로 통과합니다. 자동 모드의 가드가 잡는 건 태국·키릴 문자처럼 네 언어 어디에도 없는 문자뿐입니다. 한국어 강의라면 설정에서 음성 인식 언어를 "한국어"로 지정하는 것이 가장 확실합니다. 힌트가 하나면 strict가 가장 견고하고, 가드도 분류해 둔 다른 문자(가나·한자·키릴·태국 등)를 모두 걸러 냅니다. 버린 발화는 화면에 남지 않지만, 다른 문자로 찍힌 몇 초짜리 문장은 어차피 읽을 수 없어서 버리는 쪽을 택했습니다.
어떻게 검증했나
유닛 테스트. 조기 확정 규칙은 서버 메시지를 소켓 없이 흘려 넣는 테스트용 진입점(handleServerMessage)을 만들어 다섯 가지 경우로 고정했습니다.
- 평소처럼 쉬어 가며 말하면 지금처럼
<end>까지 기다린다. - 12초를 넘겨도 문장 중간이면 기다리고, 12초 지점 이후 문장 끝이 오면 거기까지만 확정한다. 남은 토큰은 임시 줄에 남았다가 다음
<end>에 나간다. - 문장 끝이 있어도 그 위치가 12초 이전이면 자르지 않는다.
- 문장 끝이 전혀 없으면 30초에서 무조건 확정한다.
- 조기 확정 뒤 같은 토큰이 다시 와도 두 번 나가지 않는다.
문자 체계 가드는 아홉 가지 경우로 고정했습니다. 한국어 속 영어 용어나 문장 끝에 섞인 가나 한 글자는 통과하고, 한국어 힌트에서 가나·한자 문장과 자동 힌트에서 태국·키릴 문장은 버려지며, 모르는 힌트 코드에서는 가드가 꺼지는 식입니다.
시뮬레이터. 수정한 빌드로 긴 노트를 열고 녹음하자 첫 문장에서 바닥으로 내려갔고, 위로 끌어 올리면 멈췄다가 바닥으로 내리면 다시 따라갔습니다. 쉼을 줄인 원고에서도 확정이 계속 들어오고 임시 줄이 화면 안에 머물렀습니다. 정적 분석 경고 0건, 전체 테스트 224개 통과를 확인하고 1.2.8로 내보냈습니다.
시뮬레이터가 보여 주는 건 동작까지입니다. 30분이 넘는 실제 설교에서 다른 언어가 섞이지 않는지는 실기기 녹음으로 따로 확인해야 합니다.
같은 문제를 피하는 체크리스트
- 대리 지표로 사용자 의도를 추정한다면, 그 지표를 움직이는 다른 경로를 전부 적어 본다. 캐럿은 탭이나 IME 상태 복원으로도 움직입니다. 의도가 직접 드러나는 신호(드래그)가 있으면 그쪽을 씁니다.
- 꺼진 기능이 저절로 다시 켜지는지 확인한다. "조건이 거짓이면 상태를 유지"하는 코드는 그 상태가 조건을 계속 거짓으로 만들면 영구히 꺼집니다.
- 실시간 화면은 임시 텍스트까지 따라가야 한다. 사용자는 확정과 임시를 구분하지 않습니다.
- 외부 신호를 기다리는 버퍼에는 상한을 둔다. 휴지나 서버 이벤트처럼 언젠가 올 거라 믿는 신호는 오지 않을 수 있습니다. 상한은 데이터 자체의 시간(오디오 ms)으로 재면 테스트하기 쉽습니다.
- 언어 힌트가 편향인지 제한인지, strict가 보장인지 최선 노력인지 공급자 문서로 확인한다. 그리고 앱 쪽에 값싼 검증을 하나 둡니다. 문자 체계 검사는 단순하지만 엉뚱한 문자가 찍히는 것은 막아 줍니다.
- 마이크 기능은
say로 자동화한다. 원고 파일 하나로 같은 조건을 반복할 수 있고, 문장부호를 지워 쉬지 않는 화자를 흉내 낼 수 있습니다.