SoftPlayer 사용 설명서

대상 시스템에 SoftPlayer를 압축 해제하고 환경이 요구 사항을 충족하는지 확인합니다.

1. 대상 시스템이 Windows 10/11 x64인지 확인합니다.
2. SoftPlayer 패키지를 영구 디렉터리(예: C:\SoftPlayer\)에 압축 해제합니다.
3. 디렉터리에 SoftPlayer.exe, appsettings.json 및 SoftPlayerMedia\ 하위 디렉터리 구조가 있는지 확인합니다.
4. 8K 동영상 재생 시 하드웨어 디코딩을 지원하는 GPU(GTX 1060+ 이상)가 필요합니다. 4K 이하는 내장 그래픽으로도 동작합니다.

• 압축 해제된 디렉터리에 SoftPlayer.exe가 있습니다.
• SoftPlayerMedia\ 디렉터리가 사전 생성되어 있고 Video, StandBy, Audio, PPT 등의 하위 디렉터리가 있습니다.

• SoftPlayer를 안정적인 경로에 배치하세요 — 미디어 파일, 로그 및 라이선스 상태가 모두 프로그램 디렉터리를 기준으로 저장됩니다.
• 고해상도 재생을 위해 읽기 속도 200MB/s 이상의 SSD 스토리지를 권장합니다.

프로그램이 정상적으로 시작되는지 확인하고 첫 실행 온보딩을 완료합니다.

1. SoftPlayer.exe를 더블 클릭하여 실행합니다(관리자 권한 불필요).
2. 첫 실행 시 기본 브라우저에서 빠른 시작 가이드가 열립니다(첫 실행에만 해당, 이후 실행 시 건너뜀).
3. 가이드를 읽은 후 브라우저에서 http://localhost:8766/을 열어 관리 콘솔에 접속합니다.
4. Dashboard 탭에서 플레이어 상태가 정상이고 버전/라이선스 정보가 표시되는지 확인합니다.

• 브라우저에서 관리 콘솔(http://localhost:8766/)이 성공적으로 열리고 Dashboard가 표시됩니다.
• 콘솔 헤더에 버전 번호와 라이선스 상태가 표시됩니다.

첫 실행 가이드를 비활성화하려면 appsettings.json에서 System.ShowQuickStartOnFirstRun을 false로 설정하세요.

UDP를 통해 플레이어를 성공적으로 제어하고 제어 채널이 작동하는지 확인합니다.

1. SoftPlayerMedia\Video\ 디렉터리에 동영상 파일(예: test.mp4)을 배치합니다.
2. PowerShell을 열고 다음 명령을 실행합니다:
3. $udp = New-Object System.Net.Sockets.UdpClient
4. $data = [System.Text.Encoding]::UTF8.GetBytes("video:test.mp4")
5. $udp.Send($data, $data.Length, "127.0.0.1", 7600)
6. $udp.Close()
7. SoftPlayer 창에서 지정한 동영상이 재생되는지 확인합니다.

• SoftPlayer 창에서 지정한 동영상 파일이 재생되기 시작합니다.
• 관리 콘솔 Log 탭에 명령 수신 기록이 표시됩니다.

• 동영상 파일을 잘못된 디렉터리에 배치함(프로그램 루트가 아닌 SoftPlayerMedia\Video\에 있어야 함).
• 잘못된 포트 사용(기본값은 7600이며, 관리 콘솔 포트 8766이 아님).

명령 형식을 마스터하고 성공 및 실패 응답을 이해합니다.

1. 명령 형식: command:argument, 예: video:show.mp4 또는 volume:80.
2. 인수가 없는 명령은 명령 이름만 전송 가능(콜론 선택 사항), 예: play.
3. 성공 응답 형식: OK:원래-명령, 예: OK:video:show.mp4.
4. 실패 응답 형식: ERR:원래-명령:오류-메시지.
5. 미디어 파일 경로의 경우 파일명만 필요합니다 — 플레이어가 해당 하위 디렉터리를 자동으로 검색합니다: video:는 SoftPlayerMedia/Video/에서 검색.

• 명령 전송 후 OK 접두사 응답이 오면 형식과 실행이 올바른 것입니다.
• ERR 응답에는 구체적인 이유(파일 없음, 형식 오류 등)가 포함됩니다.

하위 디렉터리를 지정하려면 슬래시를 사용하세요: video:subfolder/video.mp4는 SoftPlayerMedia/Video/subfolder/에서 검색합니다.

동영상 재생 관련 모든 명령을 마스터합니다.

1. 로컬 동영상 재생: video:filename.mp4 (Video 디렉터리에서 검색).
2. 네트워크 동영상 스트림 재생: webvideo:URL (HTTP/HTTPS/RTSP/RTMP/UDP 스트림 지원).
3. 재생/재개: play: (일시 정지된 미디어 재개).
4. 일시 정지: pause: (현재 미디어 일시 정지).
5. 중지 및 대기 화면으로 복귀: stop: (환영 화면/대기 루프로 복귀).
6. 완전 중지/블랙 스크린: stoped: (전력 절약 블랙 스크린).
7. 현재 미디어 다시 재생: replay:.
8. 진행 제어: seek:밀리초 (위치 이동), forward: (10초 앞으로), backward: (10초 뒤로).
9. 재생 속도: speed:1.5 (1.5배속, 2.0배속 등 지원).

• video: 명령 후 플레이어가 지정한 파일을 재생하기 시작합니다.
• stop: 명령 후 대기 화면으로 복귀합니다(대기 파일이 설정된 경우).

• 전시장에서 장시간 대기 시 stoped: 블랙 스크린 대신 standby:를 사용하여 대기 파일을 루프하세요(블랙 스크린은 방문객이 장치가 고장났다고 생각할 수 있습니다).
• stop과 stoped는 의미가 다릅니다: stop은 환영 화면으로 복귀하고, stoped는 순수 블랙 스크린을 표시합니다.

볼륨 조정 및 오디오 재생 제어 명령을 마스터합니다.

1. 볼륨 설정(0-100): volume:80 (정확한 값으로 설정).
2. 볼륨 10% 증가: volup: (호출 시마다 10% 증가).
3. 볼륨 10% 감소: voldown: (호출 시마다 10% 감소).
4. 음소거 토글: mute: (음소거/해제 전환).
5. 명시적 음소거: muteon:.
6. 명시적 음소거 해제: muteoff:.
7. 오디오 파일 재생: audio:filename.mp3 (SoftPlayerMedia/Audio/에서 검색).
8. 오디오 중지: audiostoped:.

• volume:50 후 플레이어 볼륨이 50%로 낮아집니다.
• mute:가 소리와 무음 사이를 전환합니다.

루프 목록, PPT 페이지 전환, 웹 로드 명령을 마스터합니다.

1. 재생 목록 루프: listloop:file1.mp4;file2.mp4;file3.mp4 (파일은 세미콜론으로 구분).
2. 순차 재생(끝에서 정지): liststop:filename.
3. 다음 트랙: next:, 이전 트랙: prev:.
4. 전체 화면 PPT 열기: ppt:filename.pptx (SoftPlayerMedia/PPT/에서 검색).
5. PPT 탐색: ppt:next (다음 슬라이드), ppt:prev (이전), ppt:home (첫 번째), ppt:end (마지막).
6. 슬라이드로 이동: ppt:goto-5 (5페이지로 이동).
7. PPT 자동 넘김: ppt:auto-5-filename.pptx (5초마다 자동 넘김).
8. 웹 페이지 로드: web:URL (지정한 URL을 전체 화면으로 표시).

• listloop: 명령 후 플레이어가 나열된 파일을 순환 재생합니다.
• ppt:next가 PPT의 다음 슬라이드로 넘어갑니다.

• PPT 파일은 명령을 보내기 전에 SoftPlayerMedia/PPT/에 배치해야 합니다.
• PDF 파일의 경우 키 입력 시뮬레이션으로 페이지를 넘기는 뷰어 창으로 대체됩니다.
• 전시장 루프 시나리오에서는 개별 명령을 수동으로 보내는 대신 listloop을 사용하세요.

마스크 및 시스템 수준 명령을 이해합니다.

1. 마스크 오버레이 표시: openmask: (동영상 위에 마스크 레이어 오버레이).
2. 마스크 오버레이 숨기기: closemask:.
3. 재생 종료 동작 설정: endbehavior:Stop / Loop / Standby.
4. 버전 확인: version: (응답에 현재 버전 정보 포함).
5. 플레이어 재시작: restart: (플레이어 프로세스를 원격으로 재시작).

• openmask: 후 동영상 위에 마스크 오버레이가 나타납니다.
• version: 후 버전 정보가 포함된 응답을 받습니다.

각 미디어 파일 유형의 올바른 위치를 파악합니다.

1. SoftPlayerMedia/Video/ — 동영상 파일(.mp4/.mkv/.avi 등), video: 명령에서 사용.
2. SoftPlayerMedia/StandBy/ — 대기 파일, standby: 명령 및 기본 루프에서 사용.
3. SoftPlayerMedia/Audio/ — 오디오 파일(.mp3/.wav/.flac 등), audio: 명령에서 사용.
4. SoftPlayerMedia/BackgroundAudio/ — 배경 오디오, 활성화 시 자동 루프.
5. SoftPlayerMedia/PPT/ — PPT/PDF 파일, ppt: 명령에서 사용.
6. SoftPlayerMedia/Mask/ — 마스크 이미지, openmask: 명령에서 사용.
7. SoftPlayerMedia/Thumbnail/ — 썸네일 캐시 디렉터리(자동 생성, 수동 파일 불필요).

• Video/에 동영상을 배치한 후 video:filename 명령으로 올바르게 재생됩니다.
• 디렉터리 구조는 첫 실행 시 자동으로 생성됩니다 — 수동 설정 불필요.

브라우저 관리 콘솔을 통해 일상적으로 미디어 파일을 관리합니다.

1. 브라우저에서 http://플레이어-IP:8766/을 열어 관리 콘솔에 접속합니다.
2. 상단 탐색을 클릭하여 Files 탭으로 전환합니다.
3. 대상 디렉터리(Video / StandBy / Audio / PPT 등)를 선택합니다.
4. Upload를 클릭하여 파일을 선택하거나 파일을 업로드 영역으로 드래그합니다.
5. 폴더 생성, 이름 바꾸기, 파일/폴더 삭제, 파일 다운로드를 지원합니다.
6. 파일은 최대 3개의 하위 디렉터리 수준을 지원합니다. 업로드 시 현재 디렉터리를 선택하세요.

• 업로드 후 새로 업로드된 파일이 파일 목록에 나타납니다.
• video:filename 명령으로 방금 업로드한 파일이 성공적으로 재생됩니다.

• 콘솔은 Basic Auth를 사용합니다 — appsettings.json에서 사용자 이름/비밀번호를 구성하세요.
• 기본 단일 파일 업로드 한도는 500MB이며, 설정 파일에서 변경 가능합니다.
• 현장 유지 관리 직원이 RDP 없이 콘솔을 통해 교체 콘텐츠를 업로드할 수 있습니다.

체험 규칙을 이해하고 라이선스 타이밍을 적절히 계획합니다.

1. 30일 체험은 SoftPlayer 첫 실행 시 자동으로 시작됩니다.
2. 체험 기간 중 고해상도 재생 및 모든 UDP 명령을 포함한 모든 기능을 사용할 수 있습니다.
3. 관리 콘솔 Dashboard 탭에서 남은 체험 일수를 확인합니다.
4. 체험 후에는 계속 사용하려면 라이선스 코드를 가져와야 합니다.

• 관리 콘솔 Dashboard에 현재 체험 상태와 남은 일수가 표시됩니다.
• 체험 기간 중 명령이 정상적으로 응답하며 기능 제한이 없습니다.

• 정식 프로젝트 납품 전에 테스트와 검수를 완료하기 위해 체험 기간을 활용하세요.
• 전시장 다운타임을 방지하기 위해 체험 만료 전에 라이선스를 구매하세요.

실제 전시장 해상도 요구에 맞는 라이선스 등급을 선택합니다.

1. Standard 라이선스: 최대 4K 해상도(3840×2160) 지원.
2. Professional 라이선스: 최대 16K 해상도(15360×8640) 지원.
3. 4K 하드웨어 요구 사항: Intel i3+, 8GB RAM, 내장 그래픽(외장 GPU 불필요).
4. 8K 하드웨어 요구 사항: Intel i5 8세대+, 16GB RAM, GTX 1060+.
5. 16K 하드웨어 요구 사항: Intel i7+, 32GB RAM, RTX 3070+.
6. 어떤 등급이 필요한지 확실하지 않다면, 구매 전에 체험을 통해 실제 해상도 요구 사항을 확인하세요.

• 라이선스 등급이 프로젝트 디스플레이 장치의 최대 해상도와 일치합니다.
• 서버 하드웨어 구성이 대상 해상도의 최소 요구 사항을 충족합니다.

외장 GPU가 없는 컴퓨터는 4K 이하를 재생할 수 있습니다(프로그램이 자동으로 소프트웨어 디코딩으로 전환). 8K/16K는 적합한 외장 GPU가 필요합니다.

라이선스 코드를 가져와 체험 버전에서 정식 버전으로 업그레이드합니다.

1. 관리 콘솔 Dashboard에서 기기 ID 필드를 찾아 복사합니다.
2. 공급업체에 기기 ID를 제공하고 필요한 등급(Standard/Professional)을 명시합니다.
3. 라이선스 코드를 받은 후 콘솔 Configuration 탭으로 이동하여 라이선스 관리 섹션을 찾습니다.
4. 입력 필드에 라이선스 코드를 붙여넣고 라이선스 가져오기를 클릭합니다.
5. 가져오기 성공 후 Dashboard 라이선스 상태가 체험에서 Standard 또는 Professional로 변경됩니다.

• 관리 콘솔 Dashboard에 정식 버전 상태(Standard 또는 Professional)가 표시됩니다.
• 고해상도 동영상 재생이 더 이상 제한되지 않습니다.

• 잘못된 기기에 라이선스 코드 적용(코드는 기기에 바인딩됨; 새 시스템에는 새 코드가 필요).
• 체험 만료 후에 라이선스를 신청하여 전시장 다운타임이 발생하는 경우.

UDP 명령 제어 채널을 복구합니다.

1. SoftPlayer가 실행 중인지 확인합니다(작업 표시줄이나 작업 관리자에서 확인).
2. 명령의 포트가 appsettings.json의 UdpPort 설정(기본 7600)과 일치하는지 확인합니다.
3. Windows 방화벽이 포트 7600의 UDP 인바운드 트래픽을 허용하는지 확인합니다.
4. IP 화이트리스트가 활성화된 경우(IpWhitelistEnabled: true) 발신자 IP가 AllowedIps에 있는지 확인합니다.
5. 관리 콘솔 Log 탭에서 명령 수신 기록을 확인하여 명령이 플레이어에 도달하는지 확인합니다.

• 관리 콘솔 로그에 명령 수신 기록이 표시되어 UDP 채널이 작동하는 것을 확인합니다.
• volume:50 전송 시 플레이어 볼륨이 변경됩니다.

• 실제 IP를 사용하기 전에 먼저 127.0.0.1(localhost)로 테스트하여 네트워크 문제를 배제하세요.
• SoftControl에서 전송할 때 SoftControl UDP 명령 프로토콜과 포트가 SoftPlayer 구성과 일치하는지 확인하세요.

미디어 파일 재생 실패를 진단하고 해결합니다.

1. 동영상 파일이 SoftPlayerMedia\Video\에 있는지 확인합니다(프로그램 루트 디렉터리가 아님).
2. 파일명은 대소문자를 구분합니다 — 명령의 이름이 확장자를 포함한 실제 파일명과 정확히 일치하는지 확인하세요.
3. 하위 디렉터리의 파일은 상대 경로를 포함하세요: video:subfolder/video.mp4.
4. 관리 콘솔 Files 탭을 탐색하여 파일이 실제로 있는지 확인하세요.
5. 일반적이지 않은 파일 형식의 경우 관리 콘솔 로그에서 VLC 오류 메시지를 확인하세요.
6. 동일한 파일을 시스템에서 VLC Player로 직접 열어 파일 손상을 배제하세요.

• 관리 콘솔 파일 목록에 대상 파일이 표시됩니다.
• 명령의 파일명이 파일 목록에 표시된 것과 정확히 일치합니다.

• 명령의 파일명에 전각 공백이나 문자가 포함되어 파일을 찾을 수 없는 경우.
• 파일 확장자 대소문자 불일치(예: 명령에 .MP4를 사용했지만 실제 파일은 .mp4인 경우).

고해상도 동영상 재생 성능 문제를 해결합니다.

1. 현재 라이선스 등급을 먼저 확인하세요: Standard는 4K만 지원, Professional은 16K 지원.
2. GPU가 하드웨어 디코딩을 지원하는지 확인하세요(8K에는 GTX 1060+ 이상 필요).
3. 작업 관리자 성능 탭에서 GPU 디코드 사용률을 확인하세요 — 100%에 가까우면 GPU 병목을 나타냅니다.
4. 디스크 읽기 속도 요구 사항을 확인하세요: 4K는 25-50 Mbps, 8K는 80-100 Mbps, 16K는 200+ Mbps.
5. HDD 읽기 병목을 방지하기 위해 고해상도 동영상 파일을 SSD에 저장하세요.
6. VLC 파라미터 조정은 프로그램 디렉터리의 내장 문서(docs\User Manual.html)를 참조하세요.

• 라이선스 등급이 필요한 재생 해상도와 일치합니다.
• 하드웨어 구성이 대상 해상도의 최소 요구 사항을 충족합니다.

브라우저 관리 콘솔 접속을 복구합니다.

1. SoftPlayer가 실행 중인지 확인합니다.
2. 먼저 http://localhost:8766/로 로컬에서 접속을 시도하여 네트워크 문제를 배제합니다.
3. appsettings.json에서 HttpMonitor.Enabled가 true이고 포트가 8766인지 확인합니다.
4. Windows 방화벽이 포트 8766의 TCP 트래픽을 허용하는지 확인합니다.
5. 다른 프로그램이 포트를 점유하고 있다면 appsettings.json의 HttpMonitor.Port를 변경하고 재시작하세요.

• 브라우저에서 http://localhost:8766/에 접속하여 관리 콘솔이 표시됩니다.
• 관리 콘솔 Dashboard에 플레이어 런타임 상태가 표시됩니다.