문제 해결

OpenShot에서 정지, 충돌 또는 오류 메시지와 같은 문제가 발생하는 경우, 문제 해결에 유용한 다양한 방법이 있습니다.

문제 해결을 위한 로그 사용하기

로그는 OpenShot이 수행하는 작업과 경고 및 오류를 기록하는 텍스트 파일입니다. 이러한 파일은 화면에 오류 메시지가 표시되지 않아도 지원팀이 문제를 이해하는 데 도움이 될 수 있습니다.

OpenShot은 홈 폴더 내의 .openshot_qt 폴더에 두 개의 로그 파일을 보관합니다. Linux와 macOS에서는 이 위치가 ~/.openshot_qt/로 표시됩니다. 이 폴더는 파일 관리자에서 숨겨져 있을 수 있습니다.

두 개의 로그 파일
파일	기록 내용
`openshot-qt.log`	편집기 활동: OpenShot 시작, 프로젝트 불러오기, 설정 변경 및 인터페이스 사용. 문제를 조사할 때 보통 가장 먼저 확인하는 곳입니다.
`libopenshot.log`	OpenShot의 비디오 및 오디오 엔진 활동으로, 미디어를 읽고 미리보기 및 내보낸 비디오에 사용되는 영상과 소리를 생성하는 부분입니다. 자세한 엔진 로그는 재생 및 내보내기 문제를 조사하는 데 도움이 됩니다.

이 파일들은 동일한 애플리케이션의 서로 다른 부분을 기록합니다. 문제를 보고할 때 가능하면 두 파일 모두 포함하세요. 모든 내용을 직접 이해할 필요는 없습니다.

OpenShot의 어느 부분을 로그할지 선택하세요

편집 → 환경설정 → 고급을 열어 이 두 설정을 찾으세요:

환경설정 및 일치하는 터미널 옵션
환경설정	일치하는 인수	로그 파일
사용자 인터페이스 디버그 로그	`--debug-ui`	`openshot-qt.log`
비디오 및 오디오 엔진 디버그 로그	`--debug-engine`	`libopenshot.log`

두 환경설정 모두 기본적으로 꺼져 있어 일반 요약 메시지를 유지합니다. 하나를 켜면 해당 로그 파일에 즉시 세부 정보가 추가됩니다. 다른 로그나 터미널 메시지는 변경되지 않습니다. 환경설정은 사용자가 끌 때까지 실행 간에 유지됩니다.

사용자 인터페이스 디버그 로그는 시작, 프로젝트 불러오기, 설정 또는 인터페이스 문제의 좋은 출발점입니다. 비디오 및 오디오 엔진 디버그 로그는 비디오 및 오디오 처리에 관한 세부 정보를 추가하여 재생 및 내보내기 문제 조사에 도움이 됩니다. 엔진 로그는 매우 빠르게 커질 수 있어 OpenShot 속도를 저하시킬 수 있습니다. 문제를 재현하기 직전에 이 설정을 켜고, 완료 후에는 끄세요.

엔진 환경설정은 이전에 디버그 모드 (상세)라고 불렸습니다. 저장된 켜기/끄기 설정은 새 이름으로 이어집니다.

한 번 실행할 때 터미널 사용하기

터미널은 명령어를 입력하는 창입니다. 일치하는 인수는 환경설정과 동일한 추가 세부 정보를 활성화하며 터미널에 표시합니다:

openshot-qt --debug-ui

이 옵션은 한 번 실행 시 인터페이스 세부 정보를 기록합니다. 익숙한 --debug 및 짧은 -d 옵션은 --debug-ui와 동일한 의미입니다. 비디오 및 오디오 엔진 세부 정보는 다음을 사용하세요:

openshot-qt --debug-engine

두 가지 세부 정보를 함께 수집하려면:

openshot-qt --debug-ui --debug-engine

문제를 일으키는 단계를 반복한 후 OpenShot을 닫고 로그를 수집하세요. 이 인수들은 저장된 환경설정을 변경하지 않습니다. OpenShot을 정상적으로 시작하면 평소의 로그 설정으로 돌아갑니다.

openshot-qt.log는 약 25MB에 도달하면 새 파일을 시작하고 이전 파일 3개를 보관합니다. libopenshot.log는 메시지가 추가될수록 계속 커집니다. 필요한 로그를 저장한 후 OpenShot이 닫혀 있을 때 오래된 로그 파일을 삭제할 수 있습니다.

기타 명령줄 옵션

대부분 사용자는 위의 두 가지 제어만 필요합니다. 다음 옵션은 파일에 기록되거나 터미널에 표시되는 세부 정보의 양을 선택할 수 있게 합니다. 여기서 console은 터미널 출력을 의미합니다.

로그 옵션
옵션	기능
`--debug-ui`, `--debug`, 또는 `-d`	사용자 인터페이스 디버그 로그를 파일과 터미널에서 활성화합니다.
`--debug-engine`	비디오 및 오디오 엔진 디버그 로그를 파일과 터미널에서 활성화합니다.
`--debug-file`	터미널 세부 정보 없이 `openshot-qt.log`에 편집기 세부 정보를 추가합니다.
`--debug-console`	파일 세부 정보 없이 터미널에 편집기 세부 정보를 추가합니다.
`--log-level LEVEL`	두 로그와 터미널 출력의 세부 수준을 설정합니다.
`--log-file-level LEVEL`	터미널 설정은 변경하지 않고 두 로그 파일의 세부 수준을 설정합니다.
`--log-console-level LEVEL`	편집기와 엔진 모두에 대해 터미널의 상세 수준을 설정하며, 파일 설정은 변경하지 않습니다.

LEVEL 을 debug 로 바꾸면 상세 메시지를, info 로 바꾸면 일반 요약을 표시합니다. warning 은 경고와 오류를, error 는 오류와 치명적 실패를, critical 은 치명적 실패만 표시합니다. off 는 일반 로그 메시지를 중지하지만 기존 충돌 진단은 여전히 기록될 수 있습니다. DEBUG 와 같은 대문자 이름도 작동합니다.

예를 들어, 터미널은 평소 수준으로 유지하면서 두 파일 모두에서 상세 메시지를 수집하려면:

openshot-qt --log-file-level debug

이 옵션은 대용량 엔진 로그도 활성화하므로 잠시만 사용하세요. 이전의 --debug-file 및 --debug-console 옵션도 --help 에는 없지만 여전히 작동합니다.

환경 변수

환경 변수는 프로그램이 시작될 때 전달되는 이름이 지정된 설정입니다. 스크립트에서 OpenShot을 시작하거나 지원 담당자가 특정 설정을 시도해 보라고 할 때 유용합니다. 일반적인 사용에서는 설정할 필요가 없습니다.

선택적 환경 설정
변수	제어 대상
`OPENSHOT_LOG_LEVEL`	두 파일과 터미널 모두의 상세 정보.
`OPENSHOT_LOG_FILE_LEVEL`	두 파일에만 상세 정보.
`OPENSHOT_LOG_CONSOLE_LEVEL`	OpenShot의 두 부분 모두에 대해 터미널에만 상세 정보.
`LIBOPENSHOT_LOG_LEVEL`	비디오 및 오디오 엔진에 대한 상세 정보, 파일과 터미널 모두.
`LIBOPENSHOT_LOG_FILE_LEVEL`	`libopenshot.log` 에만 상세 정보.
`LIBOPENSHOT_LOG_CONSOLE_LEVEL`	터미널에만 엔진 상세 정보.

예를 들어, 이 Linux/macOS 터미널 명령은 한 번 실행 시 엔진 로그 파일에 상세 로그를 요청합니다:

LIBOPENSHOT_LOG_FILE_LEVEL=debug openshot-qt

설정이 겹칠 경우 명령줄 옵션이 우선하며, 그 다음이 환경 변수, 환경 설정, 그리고 기본값 순입니다. 각 설정은 자신이 설명하는 출력에만 영향을 줍니다: --debug 는 엔진 환경 설정을 덮어쓰지 않습니다. 임시 덮어쓰기는 저장된 환경 설정을 변경하지 않습니다. 체크박스 위에 마우스를 올리면 다른 설정이 해당 로그 파일을 제어하는지 확인할 수 있습니다.

환경 설정 내에서 엔진에 대해 LIBOPENSHOT_ 값이 OPENSHOT_ 값보다 우선합니다. 각 그룹 내에서는 파일 전용 또는 콘솔 전용 수준이 일반 수준보다 우선합니다. 명령줄 옵션도 동일한 파일/콘솔 규칙을 따릅니다. 동일 출력에 대한 상충하는 명령줄 수준은 거부되며, 잘못된 환경 수준은 보고되고 무시됩니다.

이전 스크립트의 경우, LIBOPENSHOT_DEBUG 가 존재하면 값이 0 이더라도 터미널에서 상세 엔진 메시지를 활성화합니다. 최신 수준 설정이 이를 우선합니다. LIBOPENSHOT_LOG_FILE 은 엔진을 별도로 사용하는 프로그램용이며, OpenShot 자체는 위의 로그 폴더를 사용합니다. 로그 설정 변경은 오류 보고 환경 설정을 변경하지 않습니다.

Windows 11 응답 없음

Windows 11에서 정지가 발생하면, 이는 PyQt5와 Windows 11의 알려진 문제로, Qt의 접근성 기능과 관련이 있습니다. OpenShot에서 Ctrl+C 를 누르면 (Windows 11에서만) 이 문제가 발생합니다. OpenShot이 응답하지 않게 되고 메모리 누수도 발생합니다(즉, OpenShot이 응답하지 않는 시간이 길어질수록 메모리 누수가 커져 결국 OpenShot이 충돌하거나 사용자가 프로세스를 종료할 때까지 계속됩니다).

간단한 해결책은 Windows 11에서 Ctrl+C 를 피하고 대신 마우스 오른쪽 클릭 복사/붙여넣기 메뉴를 사용하는 것입니다. 또 다른 해결책은 “복사” 단축키를 Ctrl+C 에서 Alt+C 와 같이 다른 키로 재설정하는 것입니다. OpenShot 환경 설정에서 키보드 매핑을 변경할 수 있습니다. 키보드 를 참조하세요.

Windows에서 GDB로 디버깅하기

Windows 10/11에서 OpenShot이 충돌하거나 정지하는 경우, 다음 단계별 지침이 충돌 원인을 파악하는 데 도움이 됩니다. 이 지침은 충돌 위치에서 OpenShot 소스 코드의 스택 추적을 표시합니다. 이 정보는 개발팀에 매우 유용하며, 버그 보고서에 첨부하면 문제 해결이 빨라집니다.

MSYS2 설치

Windows용 OpenShot은 MSYS2라는 환경에서 컴파일됩니다. GDB 디버거를 실행 파일 openshot-qt.exe 에 연결하려면 먼저 MSYS2를 설치해야 합니다. 이 단계는 한 번만 필요합니다.

MSYS2 다운로드 및 설치: http://www.msys2.org/
MSYS2 MinGW x64 명령 프롬프트 실행 (예: C:\msys64\msys2_shell.cmd -mingw64)
모든 패키지 업데이트 (다음 명령어 복사/붙여넣기):
```
pacman -Syu
```

GDB 디버거 설치 (다음 명령어 복사/붙여넣기):

pacman -S --needed --disable-download-timeout mingw-w64-x86_64-toolchain

GDB 디버거로 OpenShot 실행

MSYS2 MinGW x64 명령 프롬프트 실행 (예: C:\msys64\msys2_shell.cmd -mingw64)

PATH 업데이트 (다음 명령어 복사/붙여넣기):

export PATH="/c/Program Files/OpenShot Video Editor/lib:$PATH"
export PATH="/c/Program Files/OpenShot Video Editor/lib/PyQt5:$PATH"

GDB 디버거에 OpenShot 로드 (다음 명령어 복사/붙여넣기):

cd "/c/Program Files/OpenShot Video Editor"/
gdb openshot-qt.exe

GDB 프롬프트에서 OpenShot 실행 (다음 명령어 복사/붙여넣기):

run --debug

디버깅 정보 출력

GDB가 연결된 상태로 OpenShot이 성공적으로 실행되면, OpenShot에서 충돌이나 정지를 유발하면 됩니다. 충돌이 발생하면 MSYS2 MinGW64 터미널로 돌아가 다음 명령어 중 하나를 입력하고 ENTER를 누르세요. 보통 처음 입력하는 명령어는 bt (백트레이스)입니다. 더 많은 명령어가 아래에 나와 있습니다.

(gdb) run            (launch openshot-qt.exe)
(gdb) CTRL + C       (to manually break out   OR   wait for a crash / segmentation fault)
(gdb) bt             (Print stack trace for the current thread #)
(gdb) info threads   (to view all threads, and what they are doing. Look for `__lll_lock_wait` for Mutex/deadlocks)
(gdb) thread 35      (Switch to thread number, for example thread 35)

고해상도 DPI / 4K 모니터

OpenShot Video Editor는 고해상도 DPI(인치당 도트 수) 모니터를 강력하게 지원하여, 다양한 DPI 설정을 가진 디스플레이에서도 인터페이스가 선명하고 쉽게 읽히도록 보장합니다. 이 지원은 특히 4K 모니터 및 기타 고해상도 디스플레이에서 유용합니다.

모니터별 DPI 인식

OpenShot은 모니터별로 DPI를 인식하여, 연결된 각 모니터의 DPI 설정에 따라 스케일링을 동적으로 조정할 수 있습니다. 이를 통해 다양한 디스플레이에서 일관된 사용자 경험을 제공합니다.

Windows에서의 DPI 스케일링

Windows에서는 OpenShot이 시각적 완성도를 유지하기 위해 스케일링 비율을 가장 가까운 정수로 반올림합니다. 이는 UI에서 시각적 왜곡을 방지하고 인터페이스 요소를 선명하고 잘 정렬되게 유지하는 데 도움이 됩니다. 이 반올림 때문에 일부 스케일링 옵션은 예상보다 더 큰 글꼴과 UI 요소를 초래할 수 있습니다.

125% 스케일링 은 100% 로 반올림됩니다
150% 스케일링 은 200% 로 반올림됩니다

세밀한 조정을 위한 우회 방법

반올림은 깔끔한 인터페이스 유지를 돕지만, 스케일링을 더 정밀하게 제어하려는 사용자를 위한 우회 방법도 있습니다. 이 방법들은 시각적 왜곡이 발생할 수 있으므로 권장되지 않습니다:

QT_SCALE_FACTOR_ROUNDING_POLICY=PassThrough
- 이 환경 변수를 설정하면 반올림이 비활성화되어 더 정밀한 스케일링이 가능합니다.
- 참고: 이로 인해 특히 타임라인에서 시각적 왜곡이 발생할 수 있으므로 권장되지 않습니다.
QT_SCALE_FACTOR=1.25 (또는 유사한 값)
- 스케일 팩터를 수동으로 설정하면 글꼴과 UI 스케일링을 더 세밀하게 조정할 수 있습니다.
- 이 설정은 환경 설정(사용자 인터페이스 스케일)에서도 할 수 있지만, Windows에서 소수점 스케일을 사용할 경우 테두리/선 문제 발생이 예상됩니다.
- 참고: 이 방법 역시 시각적 왜곡을 유발할 수 있으며 OpenShot 사용을 어렵게 만들 수 있습니다.

이 환경 변수 조정에 대한 자세한 정보는 https://github.com/OpenShot/openshot-qt/wiki/OpenShot-UI-too-large 를 방문해 주세요.