디버그 & 로그 (Debug & Log)¶
VoiceScriptPlayer는 실행 중 발생하는 모든 예외, 이벤트, 경고를
자동으로 로그 파일로 기록합니다.
이 기능은 문제 진단이나 스크립트 동작 검증에 매우 유용하게 활용할 수 있습니다.
1. 로그 파일 위치¶
모든 로그는 기본적으로 내문서경로에 저장됩니다.
C:\Users\<사용자명>\Documents\VoiceScriptPlayer\Log
2. 로그 파일 형식¶
로그 파일은 날짜 또는 카테고리에 따라 자동으로 분류됩니다.
| 파일 이름 예시 | 설명 |
|---|---|
| 2025--.log | 일반 실행 중 발생한 전체 로그. 에디터, 서비스, 백엔드 전반의 기록이 포함됩니다. |
| 2025-__-___Player.log | 실행 모드(Playback)에서 발생한 오류나 예외 로그. Player 전용 이벤트 기록입니다. |
모든 로그 파일은 UTF-8 인코딩으로 저장되며,
하루 단위로 자동 생성됩니다.
3. 로그 카테고리¶
각 로그 항목은 다음과 같은 카테고리(Category) 로 구분됩니다.
| 카테고리 | 설명 |
|---|---|
| UI | 사용자 인터페이스 관련 예외. 버튼, 창, 컨트롤 동작 등 |
| Domain | 프로젝트 로직, 데이터 처리, 내부 연산 과정의 오류 |
| Task | 비동기 작업, 타이머, 백그라운드 프로세스 관련 오류 |
| Player | 실행 모드(Playback) 또는 편집 중 재생 시 발생한 오류. 장치, 파일, 실행 제어 관련 예외 |
💡 팁:
“Player” 로그는 실제 실행 환경에서만 생성되며,
에디터에서도 재생 중이라면 동일한 방식으로 기록됩니다.
4. 로그 구조 예시¶
아래는 2025-__-___Player.log에 기록된 실제 로그의 축약 예시입니다.
============================================================
[Time] 2025-__-__ __:__:__
[Category] Player
[Caller] ExceptionHandler
[Type] System.IO.FileNotFoundException
[Message] Could not find file '...Sound1.audio'.
[Source] System.Private.CoreLib
[Target] Microsoft.Win32.SafeHandles.SafeFileHandle.CreateFile(...)
[StackTrace]
at System.IO.File.ReadAllText(String path)
at VoiceScriptPlayer.Models.AudioItem..ctor(...)
at VoiceScriptPlayer.Core.Event.AudioEvent.get_AudioItem() ...
============================================================
5. 로그 해석 방법¶
| 항목 | 설명 |
|---|---|
| [Time] | 오류 또는 이벤트 발생 시각 |
| [Category] | 발생한 모듈 또는 영역 |
| [Caller] | 호출한 함수 또는 처리기 이름 |
| [Type] | 예외 형식 (System.Exception, FileNotFoundException 등) |
| [Message] | 오류의 요약 메시지 |
| [Source] | 오류가 발생한 어셈블리 또는 네임스페이스 |
| [Target] | 실제 호출된 메서드 서명 |
| [StackTrace] | 발생 지점의 코드 경로 (디버그 추적용) |
💡 참고:
스택 트레이스(StackTrace)는 내부 개발용 디버깅 정보이며,
일반 사용자는 세부 코드를 이해하지 않아도 됩니다.
로그의 상단에 있는 [Message] 항목만 확인해도
대부분의 오류 원인을 파악할 수 있습니다.
6. 플레이 중단 (Playback Halt)¶
Player 카테고리의 오류는 단순 기록이 아닌,
실시간으로 화면에 표시되며 재생이 자동으로 중단됩니다.
- 오류 메시지는 화면에 붉은색 텍스트로 표시됩니다.
- 동시에 해당 내용이
Player.log파일에 기록됩니다. - 이 상태에서는 재생이 완전히 멈추며,
문제가 해결되기 전까지 프로젝트를 다시 시작할 수 없습니다.
예시:
파일을 찾을 수 없습니다.
C:\Users\Documents\VoiceScriptPlayer\Project\새 프로젝트\Asset\Sound\새 사운드.wav
💡 참고:
이 동작은 편집기(에디터 모드)와 실행기(Playback 모드)에서 모두 동일하게 발생합니다.
즉, 재생 중 파일 누락이나 장치 오류가 발생하면 즉시 정지됩니다.
7. 문제 발생 시 안내¶
VoiceScriptPlayer는 예기치 않은 오류가 발생해도 자동으로 로그를 남깁니다.
만약 재현 가능한 문제나 비정상적인 동작이 반복된다면,
해당 로그 파일과 함께 문제 현상을 자세히 설명하여 개발자에게 전달해 주세요.
예를 들어 다음과 같은 정보를 함께 포함해 주세요:
- 오류가 언제, 어떤 상황에서 발생했는지
- 어떤 기능을 사용 중이었는지
- 오류 발생 후 어떤 현상이 나타났는지
개발자는 이 로그를 통해 원인을 빠르게 분석하고 수정할 수 있습니다.
(버그 제보 채널은 추후 공식적으로 공지될 예정입니다.)
8. 디버그 활용 팁¶
- 프로젝트가 실행되지 않거나 멈출 때 →
Player.log확인 - UI 동작이 반응하지 않을 때 →
UI카테고리 로그 확인 - 반복적인 오류 발생 시 → 가장 최근 날짜의
.log파일을 열어 마지막 항목 확인 - 파일 누락 또는 접근 오류 →
[Message]또는[Target]항목에서 경로 확인