Pro
한국어
로그인계정 Mac용 다운로드
Mac용 다운로드

문서 / 설치와 문제 해결

설치, 업데이트, 디스크 공간

내 Mac에서 돌아갈까요? 모든 Apple Silicon Mac의 메모리, 칩, 디스크, 렌더링 시간을 한 페이지에 모았어요.

Phosphene은 Pinokio를 통해 Apple Silicon Mac(M1 이상)에서 실행돼요. 이 페이지에서는 설치와 업데이트 방법, 필요한 디스크 공간, 단계가 실패했을 때 해야 할 일을 설명해요.

Pinokio로 설치

  1. Pinokio를 설치하세요.
  2. Pinokio에서 Discover를 열고 Download from URL을 고른 다음 https://github.com/mrbizarro/phosphene을 붙여넣으세요.
  3. Install을 클릭하세요. 설치 프로그램이 먼저 여유 디스크 공간을 확인해요. 부족하면 멈추고 필요한 공간과 현재 공간을 보여 줘요.
  4. 설치가 끝나면 Start를 누르고 Open Panel을 클릭하세요. 패널이 http://127.0.0.1:8198에서 열려요.

앱은 Python 런타임과 엔진 패키지가 준비된 뒤에 열리고, 보통 몇 분 걸려요. Start를 누르기 전에도, 처음 열 때도 모델은 자동으로 내려받지 않아요. 만들고 싶은 것을 고른 다음 그에 맞는 모델을 내려받으세요.

참고 Pinokio로는 Intel Mac이나 Windows에 Phosphene을 설치할 수 없어요. Apple Silicon에서의 Linux 지원은 별개의 커뮤니티 프로젝트이고 Pinokio로는 설치되지 않아요. Linux(커뮤니티)를 참고하세요.

내려받는 것과 필요한 공간

구성다운로드시점
앱 런타임: Python과 엔진 패키지약 0.5 GB. 패키지 버전에 따라 달라질 수 있어요Start 전에. 여유 공간 18 GB가 필요하고, 그중 15 GB는 계속 비워 둬요
LTX-2.5 Q4 영상 모델(프롬프트 인코더 포함)약 27.5 GB앱 안에서 영상 모델 다운로드를 클릭하세요. 첫 영상에 권장해요
기능 추가 구성: 향상과 스토리보드 플래너를 위한 Gemma 3, 업스케일 & 얼굴 보정, 모션 컨트롤, Ingredients, Colorize용 어댑터모두 고르면 10.7 GB쓰는 것만 해당 기능이나 모델에서 내려받으세요
이미지 모델선택한 모델 옆에 표시돼요처음 생성할 때. FLUX.2 [klein] 4B는 약 4.3 GB의 가벼운 시작점이에요
LTX-2.5 Q8 가중치(학습된 캐릭터와 음성용)30.02 GB선택 사항. 설정 → 모델이나 Pinokio 사이드바에서 받아요
High 애드온(LTX의 High 품질, 키프레임, 연장용)29.50 GB선택 사항. 모델 창에서 받아요(상태 칩을 클릭한 다음 모델)
Hailuo H3, 두 번째 영상 엔진약 75 GB선택 사항. Pinokio 사이드바에서 받아요. Hailuo H3를 참고하세요
음악 엔진(YuE2)약 11 GB선택 사항. 오디오 탭이나 Pinokio 사이드바에서 받아요. 뮤직 스튜디오를 참고하세요
LTX-2.3, 캐릭터를 학습할 때만 필요해요약 20 GB, 트레이너 약 21 GB 추가캐릭터 학습을 열면 안내해 줘요

연결 속도가 100 Mbps이면 영상 모델을 받는 데 약 37분, 300 Mbps에서는 약 12분, 1 Gbps에서는 약 4분이 걸려요. 모델을 받는 동안에도 앱을 열어 둘 수 있어요. 모델 카드에는 받은 바이트 수, 현재 파일, 남은 팩이 표시돼요. 다운로드 중지는 영상 다운로드 전체를 멈춰요. 영상 모델 다운로드를 다시 클릭하면 이어서 받아요. 받은 파일은 디스크에 남아요. 모델에서 시작한 다운로드는 15 GB를 비워 두고, 공간이 부족해지면 기다려요.

기능에 필요한 추가 구성이 아직 다 내려받아지지 않았다면, 그 기능이 다운로드 안내를 표시하거나 지금 다운로드를 제안해요. 아무 안내 없이 실패하지는 않아요.

팁 설정에 Hugging Face 액세스 토큰을 추가하면 다운로드가 약 열 배 빨라질 수 있어요. 이 토큰이 꼭 필요한 애드온은 HDR뿐이에요. 나머지는 모두 토큰 없이 작동해요.

모델을 외장 드라이브에 보관하기

모델이 공간의 대부분을 차지해요. Mac 앱(5.0.20 이상)에서는 모델을 외장 드라이브에 두어 Mac의 공간을 확보할 수 있어요.

  • 설정 단계에서 모델 위치를 고르세요. 모델 저장 위치: … 줄에 변경 버튼이 있고, 그 안에 다른 드라이브 또는 폴더…가 있어요. 나중에 설정 > 모델에서 고를 수도 있어요.
  • 나중에 옮기기. 설정 > 모델의 다른 드라이브로 이동…은 모델을 드라이브로 복사하고 모든 파일을 검사해요. 그런 다음에야 Mac에 있는 사본을 지워요. 이 Mac으로 다시 이동은 모델을 다시 복사해 오고 드라이브에 있는 사본은 남겨 둬요. 공간이 필요하면 Finder에서 직접 지우세요. 이동하는 동안 진행률이 표시되고 중지 버튼이 있으며, 중지한 이동은 다시 시작하면 이어져요. 모델을 옮기는 동안 스튜디오는 닫혔다가, 옮기기가 끝나면 다시 열려요.
  • 모델만 이동해요. 앱과 엔진은 Mac에 남기 때문에 Phosphene은 항상 열려요.
  • 드라이브를 뽑았다면 앱에 *“(드라이브 이름) 연결되어 있지 않아요”*라고 표시돼요. 드라이브를 꽂고 다시 확인을 선택하거나, 대신 다운로드를 선택해 이 Mac에 초안 모델(약 27.5 GB)을 받거나, 모델 없이 열기를 선택하세요.
  • 드라이브 형식. APFS와 exFAT 드라이브는 쓸 수 있어요. FAT32는 4 GB를 넘는 파일을 담을 수 없고 일부 모델 파일은 그보다 커서, Phosphene은 FAT32 드라이브를 거부해요. 모델 일부를 Pinokio 설치와 공유한다면 APFS나 Mac OS 확장 드라이브를 쓰세요.

Phosphene을 실행하는 동안에는 드라이브를 계속 연결해 두세요.

Mac의 메모리 확인

Mac의 메모리에 따라 쓸 수 있는 품질 설정과 엔진이 정해져요. Phosphene이 자동으로 확인해요. 이 Mac에서 무엇을 실행할 수 있는지 보려면 헤더의 상태 칩을 클릭하고 등급을 선택하세요.

기능필요한 메모리
LTX 영상과 이미지모든 Apple Silicon Mac. 48 GB 미만에서는 영상 크기가 작아져요. LTX의 High 품질, 시작 & 끝 프레임, 연장은 숨겨져요. 24 GB 이하 Mac은 저메모리 영상 경로를 자동으로 써요. 16 GB Mac에서 클립 하나의 메모리 사용량은 최대 약 5.7 GB이고, LoRA를 쓰면 약 6.7 GB예요.
뮤직 스튜디오16 GB 이상. 다른 앱을 켜 둔 채 긴 노래를 만든다면 24 GB 이상을 권장해요
캐릭터 학습24 GB 이상
Hailuo H316 GB 이상(Draft와 Standard는 16 GB부터, High는 18 GB부터). 60 GB 이상이면 전체 엔진도 고를 수 있어요
LTX High · 720p64 GB Mac. 메모리 사용량이 최대 50 GB 근처까지 올라가요

긴 렌더링 전에는 탭이 많은 브라우저, Slack, iOS 시뮬레이터처럼 메모리를 많이 쓰는 앱을 닫으세요. 렌더링은 영상이나 오디오를 만드는 과정이에요. Mac의 메모리가 바닥나면 렌더링이 중단돼요. 문제 해결을 참고하세요.

Pinokio 사이드바

Pinokio에서 Phosphene을 선택하면 왼쪽 사이드바에 아래 동작들이 보여요. 어떤 동작이 보일지는 무엇이 설치되어 있는지, 패널이 실행 중인지에 따라 달라요.

  • Install / Resume Install: 필요한 파일을 설치해요. 마지막 시도가 끝나지 않았다면 Resume Install이 나타나요. 다운로드가 끝난 파일은 그대로 남아요.
  • Start, Open Panel, Terminal: Start를 클릭하면 Phosphene이 실행되고, Open Panel로 사용해요. Terminal에서는 활동 로그를 볼 수 있어요.
  • Update: 업데이트를 참고하세요.
  • Outputs, Models, Uploads: 해당 폴더를 Finder에서 열어요.
  • Install Hailuo H3 (second video engine, ~75 GB): 설치가 끝나면 Repair Hailuo H3 또는 Update Hailuo H3 runner로 바뀌어요. 둘 다 내려받은 모델 파일을 그대로 둬요.
  • Build Hailuo H3 compact engine: 16~59 GB Mac에서 모델 파일은 내려받았지만 컴팩트 엔진이 준비되지 않았을 때 나타나요. 약 5분 걸리고 내려받는 것은 없어요.
  • Install the music engine (YuE2, ~11 GB): 설치가 끝나면 Repair the music engine으로 바뀌고, 내려받은 모델 파일은 그대로 둬요.
  • Reset engine (keeps models & outputs): LTX 엔진과 필요한 소프트웨어를 다시 만들어요. 모델과 완성된 작업은 그대로 남아요. Hailuo H3에는 영향이 없어요. H3를 복구하려면 Repair Hailuo H3를 쓰세요.

Phosphene 업데이트

  • 헤더의 버전 알약에는 최신 버전, 또는 업데이트 뒤에 더 새로운 버전이 표시돼요. 업데이트가 있으면 배너의 지금 업데이트를 눌러 설치하거나, 나중에를 눌러 미뤄요.
  • Pinokio 사이드바에서 Update를 클릭하면 지원 소프트웨어를 포함한 모든 것이 업데이트돼요. 대기열, 설정, 모델, 완성된 작업은 그대로 남아요.
  • 앱 안에서 업데이트하면 배너에 *“Updated to …, restart to finish”*라고 나와요. Pinokio에서 Stop을 누른 다음 Start를 누르세요.
  • 아주 오래된 버전에서 업데이트하는데 패널만 바뀐 것 같다면 Update를 한 번 더 클릭하세요. 첫 번째 업데이트는 업데이터 자체를 교체해요.
  • Pinokio의 Update가 첫 1초 만에 멈춘다면(4.19.6 이하 버전에서 생길 수 있어요), 대신 Phosphene 자체의 배너나 버전 알약에서 지금 업데이트를 클릭한 다음 다시 시작하세요. 업데이트가 바로 멈출 때를 참고하세요.
  • 패널이 여전히 이전 버전처럼 동작한다면 다시 시작해야 해요. 그러면 버전 알약에 Restart Phosphene이 표시돼요. 그것을 클릭하거나, Pinokio에서 Stop을 누른 다음 Start를 누르세요.
  • Hailuo H3와 음악 엔진은 지원 소프트웨어가 따로 있어요. 패널이 둘 중 하나에 업데이트가 필요하다고 안내하면, Pinokio 사이드바에서 해당 엔진의 Update나 Repair 항목을 클릭하세요. 내려받은 모델 파일은 그대로 남아요.

직접 업데이트하기(업데이트가 오지 않을 때)

Phosphene은 스스로 업데이트를 확인하지만, 연결이 느리거나 막혀 있으면 업데이트가 도착하지 않을 수 있어요. 언제든 직접 최신 버전을 설치할 수 있어요. 모델, 완성된 작업, 설정, Pro 라이선스는 그대로 남아요.

Mac 앱

  1. Phosphene을 종료하세요(Phosphene → Quit, 또는 Cmd+Q).
  2. phosphene.video/download에서 최신 설치 파일을 내려받으세요(같은 파일이 각 GitHub 릴리스에도 첨부되어 있어요).
  3. 내려받은 .dmg를 열고 Phosphene을 Applications로 끌어다 놓으세요. Mac이 물으면 대체를 선택하세요.
  4. Applications에서 Phosphene을 여세요. 헤더의 버전 알약에 새 버전이 표시돼요.

복사본은 Applications에 있는 하나만 두세요. 다운로드 폴더나 설치 디스크에 남은 이전 복사본이 새 앱 대신 열릴 수 있어요. 그런 복사본은 휴지통으로 옮기고, Finder 사이드바에 있는 Phosphene 디스크는 추출하세요. 작업물은 앱 안이 아니라 ~/Library/Application Support/Phosphene에 있으므로 앱을 교체하거나 지워도 작업물은 사라지지 않아요.

Pinokio

  1. Phosphene의 Pinokio 사이드바에서 Stop을 클릭하세요.
  2. 터미널 앱을 열고 Phosphene 폴더로 이동한 다음(cd ~/pinokio/api/<your Phosphene folder>) git pull을 실행하세요.
  3. 사이드바에서 Update를 클릭한 다음 Start를 클릭하세요.

git pull이 로컬 변경 사항이 있다고 하면 먼저 git stash를 실행하고 git pull을 다시 실행하세요.

설치나 업데이트가 오류와 함께 멈출 때

필수 단계가 실패하면 Pinokio가 멈추고 FATAL error:로 시작하는 줄을 보여 줘요. 그 설치나 업데이트에 대해 Pinokio가 보여 주는 로그를 위로 스크롤하면 찾을 수 있어요. 이 줄에 문제와 다음에 클릭할 것이 적혀 있어요. 거의 모든 경우 아무것도 삭제되지 않았어요. 문제를 해결한 뒤 설치나 업데이트를 다시 클릭하면 이어서 진행돼요.

FATAL error: 뒤에 나오는 문구를 아래 표에서 찾아보세요.

줄에 적힌 내용해야 할 일
not enough disk space to install Phosphene적힌 만큼 공간을 확보한 뒤 Install을 다시 클릭하세요
could not download the video engine version Phosphene needs … (a VPN, proxy or blocked GitHub is the usual cause)연결을 확인하고 VPN이나 프록시를 끈 다음 Install이나 Update를 다시 클릭하세요
the engine environment did not install after 3 attempts인터넷 연결과 여유 디스크 공간을 확인한 다음 Install이나 Update를 다시 클릭하세요. 반복되면 아래 안내대로 그 줄을 신고하세요
the video engine is on the wrong versionInstall이나 Update를 다시 클릭하세요. 반복되면 그 줄을 신고하세요
Hailuo H3 needs a Mac with at least 16 GB of memory이 Mac에서는 H3를 실행할 수 없어요. 소리 추가를 뺀 모든 모드가 있는 LTX를 계속 쓰세요
Hailuo H3 needs about N GB of free disk space새로 설치하려면 약 97 GB(75 GB 다운로드와 22 GB 컴팩트 엔진)가 필요하고, 모델 파일을 이미 내려받았다면 약 25 GB가 필요해요. 공간을 확보한 다음 Install Hailuo H3를 다시 클릭하세요
the compact Hailuo H3 engine could not be built보통 디스크가 가득 찼다는 뜻이에요(빌드에 약 22 GB가 필요해요). 공간을 확보한 다음 Pinokio 사이드바의 H3 항목을 다시 클릭하세요. 내려받은 모델 파일로 다시 빌드해요
a Phosphene render has been running for over 60 minutes, so the compact Hailuo H3 engine was not builtPhosphene이 현재 렌더링을 끝낼 때까지 기다린 다음 Pinokio 사이드바의 H3 항목을 다시 클릭하세요
the H3 venv has no working PythonPinokio 사이드바에서 Repair Hailuo H3를 클릭하세요. 내려받은 모델 파일은 그대로 남아요
YuE2 (the music engine) needs a Mac with at least 16 GB of memory이 Mac에서는 음악 엔진을 실행할 수 없어요. Phosphene의 나머지는 영향이 없어요
YuE2 (the music engine) needs at least 14 GB free공간을 확보한 다음 Install the music engine을 다시 클릭하세요
could not download the YuE2 music engine인터넷 연결을 확인하고 VPN이나 프록시가 GitHub를 막고 있는지 살펴본 다음 Install the music engine을 다시 클릭하세요
untracked/ignored paths obstruct Update. Move them; nothing deleted.앱 폴더 안에 직접 넣은 파일이 업데이트를 방해하고 있어요. 바로 위의 줄들에 그 파일이 나열돼요. Phosphene 폴더 밖으로 옮긴 다음 Update를 다시 클릭하세요
fetch failed (offline?) - nothing changed, re-run Update다시 연결한 다음 Update를 다시 클릭하세요
the Update safety check did not pass - not updating아무것도 바뀌지 않았어요. Update를 다시 클릭하세요. 반복되면 그 줄을 신고하세요

목록에 없는 오류라면 그 FATAL error: 줄의 안내를 따르세요. 오류를 신고하려면 그 줄과 바로 위 몇 줄을 복사해 버그 신고에 붙이세요. 문제 신고하기를 참고하세요.

작업물을 잃지 않고 처음부터 다시 하기

  • Pinokio에서 Reset engine을 클릭하면 LTX 엔진을 다시 만들어요. 모델, 완성된 작업, 설정은 그대로 남아요.
  • 완성된 작업을 찾으려면 Pinokio 사이드바에서 Outputs를 클릭하세요. Phosphene 폴더 안의 mlx_outputs가 열려요.
  • 내려받은 모델을 찾으려면 사이드바에서 Models를 클릭하세요. mlx_models가 열려요. 전부 다시 내려받고 싶은 경우가 아니라면 이 폴더를 지우지 마세요.

Phosphene은 열리는데 작업이 실패하거나, 모델이 없거나, 대기열이 멈춘다면 문제 해결을 참고하세요.

출처: webapp/docs/install.md (공개 저장소). 공개 전에 이 웹사이트용으로 검토했어요. 영어 원문에서 번역했어요. 수정 제안하기.