Halcyonతో Jellyfinను 90ల వీడియో స్టోర్‌గా మార్చడం

Halcyon మీ Jellyfin లైబ్రరీతో చేసే పని

Halcyon Video మీ Jellyfin లైబ్రరీని browserలో నడిచి చూడగలిగే 1990s వీడియో స్టోర్‌గా మళ్లీ రూపొందిస్తుంది. మీ వద్ద ఉన్న ప్రతి సినిమా shelfపై ఒక caseగా కనిపిస్తుంది. Strip lights కింద aislesలో నడిచి, ఒక boxను తీసి, దాని వెనుక ఉన్న వివరాలను చదవడానికి తిప్పి చూసి, playback ప్రారంభించడానికి counter వద్దకు తీసుకెళ్లవచ్చు. Playback ప్రారంభం, progress, stop వివరాలను Jellyfinకు తిరిగి పంపుతుంది. అందువల్ల resume points మరియు watch history సరైనవిగా ఉంటాయి.

Halcyon ఇప్పటికే ఉన్న Jellyfin server నుంచి Jellyfin API ద్వారా డేటాను చదువుతుంది. ఇది తన స్వంత libraryని నిర్వహించదు. ఈ guideలో Jellyfin ఇప్పటికే నడుస్తూ, ఎలాంటి సమస్యలు లేకుండా scan చేస్తోందని భావిస్తున్నాం. అలా లేకపోతే ముందుగా VPSలో Jellyfinను media serverగా ఏర్పాటు చేయండి. సాధారణ web clientలో మీ library సరిగ్గా కనిపించిన తర్వాత ఈ guideకు తిరిగి రండి. Library ఇప్పటికే ఉన్నందునే మీరు దీన్ని install చేస్తారు. మీ self hosting జాబితాకు మరో service అవసరమైనందుకు కాదు.

ఈ project GPL-3.0 కింద విడుదలైంది. దీన్ని ఒకే వ్యక్తి రాశారు. Pull requestsను స్వీకరించబోమని READMEలో స్పష్టంగా పేర్కొన్నారు. Development వేగంగా జరుగుతోంది. Regressionను గుర్తించడానికి రెండో maintainer లేరు. అందువల్ల storeను ఇతరులకు చూపించే ముందు image versionను pin చేయండి. చివరి sectionలో దాన్ని ఎలా చేయాలో వివరించాం.

రెండరింగ్ ఎక్కడ జరుగుతుంది?

బ్రౌజర్‌లో. Halcyon అనేది three.js పై నిర్మించిన Vite మరియు TypeScript అప్లికేషన్. three.js అనేది WebGL (web graphics library; GPUకి బ్రౌజర్ అందించే interface) ద్వారా 3D గ్రాఫిక్స్‌ను గీయే JavaScript library. స్టోర్ యొక్క geometry మరియు box artలను స్క్రీన్‌ను నడుపుతున్న machine కలిపి render చేస్తుంది.

Container చాలా తక్కువ పని చేస్తుంది. అది npm run serve ను నడుపుతుంది. ఇది vite preview --port 1420 --strictPort --host. అలాగే built files మరియు కొన్ని చిన్న middleware routes ను అందిస్తుంది. Halcyon ఎలాంటి transcoding చేయదు. Server పై ఎలాంటి engine ను కూడా నడపదు.

అందువల్ల GPUకు సంబంధించిన ప్రశ్న clientకే వర్తిస్తుంది. చిన్న VPS దీన్ని సులభంగా అందిస్తుంది, ఎందుకంటే ఇందులో చేయాల్సిన పని HTTP ద్వారా static files అందించడం మాత్రమే. Browser నడుస్తున్న laptop, tablet లేదా television స్టోర్ సజావుగా కదులుతుందా లేదా నెమ్మదిగా నడుస్తుందా అనేది నిర్ణయిస్తుంది.

ఒక feature ఈ నియమానికి మినహాయింపు. Remote Play serverపై headless Chromium instances ను ప్రారంభించి, render చేసిన స్టోర్‌ను WebRTC (web real time communication) ద్వారా phone లేదా set top boxకు stream చేస్తుంది. ఈ విధానంలో rendering serverపైనే జరుగుతుంది. Defaultగా instances సంఖ్య రెండు వరకు పరిమితం ఉంటుంది. REMOTE_PLAY_MAX_INSTANCES తో ఈ పరిమితిని మార్చవచ్చు. Mapped /dev/dri device లేకపోతే, ఆ instances CPUపై render అవుతాయి. అందువల్ల two core VPSకు ప్రతి అదనపు viewer ప్రభావం స్పష్టంగా కనిపిస్తుంది.

మీ లైబ్రరీ నుంచి స్టోర్ చదివేది

స్టోర్‌లోని మార్గాలు Jellyfin స్వంత నిర్మాణం నుంచి వస్తాయి. Halcyon మీ libraries మరియు genres ఆధారంగా sections ను అమర్చుతుంది. మీ BoxSets నుంచి sequelలను సమూహాలుగా చూపిస్తుంది. ప్రతి కేసు వెనుక ముద్రించిన specs, Jellyfin ఇప్పటికే కలిగి ఉన్న MediaStreams metadata నుంచి వస్తాయి. అందువల్ల Jellyfinలో లేనిది shelfలో కూడా ఉండదు.

దీంతో స్టోర్ మీ metadataకు ఖచ్చితమైన ప్రతిబింబంగా ఉంటుంది. artwork మరియు genres ఇప్పటికే నింపిన Docker Composeలోని arr stack ద్వారా అందించబడే library ఇక్కడ చాలా మెరుగ్గా కనిపిస్తుంది. generic పేర్లతో ఉన్న విడివిడి files folder అంత మెరుగ్గా కనిపించదు.

ఏదైనా ఇన్‌స్టాల్ చేయడానికి ముందు video store డెమోను ప్రయత్నించండి

ప్రాజెక్ట్ synthetic libraryతో నడిచే పూర్తి storeను hosted demo వద్ద అందిస్తుంది. ఏదైనా Halcyon URLకు ?demo=1 ను చివర జోడిస్తే, మీ స్వంత deploymentలో కూడా అదే ఫలితం వస్తుంది.

దీనిని hardware testగా ఉపయోగించండి. డెమో libraryలో సుమారు 2,000 titles ఉన్నాయి. దీనికి browser memoryలో దాదాపు 2 GB అవసరం. ఇది చాలా personal libraryల కంటే ఎక్కువ వనరులు ఉపయోగిస్తుంది. మీరు browse చేయడానికి ఉపయోగించాలనుకునే deviceలో డెమో నెమ్మదిస్తే, మీ స్వంత library కూడా నెమ్మదిస్తుంది. దీనికి పరిష్కారం పెద్ద VPS కాదు; కింద వివరించిన 2.5D modeను ఉపయోగించడం.

Dockerతో దీన్ని నడపండి

ఇది upstream documentationలో ఉన్న command.

docker run -d --name halcyon --network host --restart unless-stopped \
  ghcr.io/halcyon-video/halcyon-video

తర్వాత ఇది సరిగ్గా ప్రారంభమైందో లేదో తనిఖీ చేయండి.

docker logs halcyon
curl -I http://127.0.0.1:1420

logలో preview server port 1420పై listening చేస్తున్నట్లు కనిపించాలి. అలాగే curl కు HTTP/1.1 200 OK సమాధానం ఇవ్వాలి. కొన్ని సెకన్లలోనే exit అయ్యే containerకు కారణం దాదాపు ఎల్లప్పుడూ port సమస్యే. --strictPort అంటే 1420 ఇప్పటికే ఉపయోగంలో ఉన్నప్పుడు server 1421కు మారడానికి నిరాకరిస్తుంది. అందువల్ల అది ఆగిపోతుంది.

--network host Remote Play కోసం మాత్రమే ఉంటుంది; store కోసం కాదు. Streamను కోరుతున్న deviceకు WebRTC యంత్రం యొక్క నిజమైన addressను తెలియజేయాలి. Default Docker bridge వెనుక containerకు తన స్వంత 172.x address మాత్రమే తెలుస్తుంది. మీ networkలోని ఏ phone కూడా ఆ addressను చేరుకోలేం. అందువల్ల stream ఎప్పటికీ connect కాదు. Browserలో store మాత్రమే ఉపయోగించాలనుకుంటే portను publish చేయండి.

docker run -d --name halcyon -p 1420:1420 --restart unless-stopped \
  ghcr.io/halcyon-video/halcyon-video

VPSలో ఇది మెరుగైన default. Host networking వల్ల container యంత్రం కలిగి ఉన్న ప్రతి interfaceపై, public interfaceతో సహా, అందుబాటులో ఉంటుంది. ఆ trade-offలో మిగతా అంశాలను VPSలో Dockerను నడపడం వివరిస్తుంది. Reboot తర్వాత storeను తిరిగి ప్రారంభించేది --restart unless-stopped. ఇది boot సమయంలో ప్రారంభమయ్యే Compose servicesలోని విధానంతో సమానం.

Repositoryను clone చేసి docker compose up -d నడిపితే imageను స్థానికంగా build చేస్తుంది. Commit చేసిన Compose file defaultగా source నుంచి build చేస్తుంది. అందులో ముందే build చేసిన image: line commentగా ఉంటుంది. Compose కింద published imageను ఉపయోగించాలనుకుంటే ఆ lineను uncomment చేయండి.

August 2026 నాటికి ఒక ముఖ్యమైన పరిమితి ఉంది: published image linux/amd64 మాత్రమే. Multi-architecture pushలోని arm64 భాగం emulation కింద విఫలమైంది. Native arm runners అందుబాటులోకి రావాల్సి ఉంది. arm64 VPSలో pull చేయడం no matching manifest for linux/arm64/v8 in the manifest list entries తో విఫలమవుతుంది. Clone నుంచి build చేయడం దీనికి పరిష్కారం.

Jellyfin server కు దాన్ని అనుసంధానించండి

http://<host>:1420 ను తెరిచి, మీ Jellyfin server address, username మరియు password తో login చేయండి. Repository లోని .env.local.example file local development కోసం మాత్రమే. VITE_ తో prefix అయ్యే variables ను Vite client-side code కు expose చేస్తుంది. అందువల్ల అక్కడ రాసిన Jellyfin password ప్రతి visitor download చేసే JavaScript bundle లో compile అవుతుంది. ఇతరులు చేరుకోగల server పై interface ద్వారా login చేయండి.

Browser నేరుగా Jellyfin తో మాట్లాడుతుంది. Halcyon container Jellyfin API కు proxy చేయదు. Debugging ప్రారంభించే ముందు తెలుసుకోవలసిన రెండు ప్రభావాలు దీనివల్ల ఉంటాయి.

మొదట, Jellyfin ను Halcyon అందించే VPS నుంచే కాకుండా browser నుంచీ కూడా చేరుకోగలగాలి. 127.0.0.1:8096 కు bind చేసిన Jellyfin local test కు సరిపోతుంది. అయితే మిగతా అందరికీ shelves ఖాళీగా కనిపిస్తాయి.

రెండవది, ఈ call cross-origin గా ఉంటుంది. ఇది Halcyon address నుంచి Jellyfin address కు వెళ్తుంది. Jellyfin API requests కు default గా Access-Control-Allow-Origin: * తో సమాధానం ఇస్తుంది. అందువల్ల అదనపు configuration అవసరం లేకుండా పనిచేస్తుంది. మీరు ఆ setting ను పరిమితం చేసి ఉంటే, లేదా Jellyfin API ముందు authentication proxy ఉంచి ఉంటే, browser console blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource ను చూపిస్తుంది. అప్పుడు store ఖాళీ shelves తో load అవుతుంది.

దాన్ని reverse proxy వెనుక ఉంచి, ముందుగా authentication అమలు చేయండి

vite preview ఒక preview server. ఇది TLS (transport layer security) termination చేయదు, అలాగే స్వంత access control కూడా లేదు. అందువల్ల publicగా అందుబాటులో ఉన్నప్పుడు దీనిని nginx లేదా Caddy వెనుక ఉంచాలి.

server {
  listen 443 ssl;
  server_name halcyon.example.com;

  location / {
    proxy_pass http://127.0.0.1:1420;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Container ముందు domain name ఉపయోగించాలంటే మరో setting అవసరం. DNS rebinding నుంచి రక్షించడానికి Halcyon localhost, raw IP addresses, అలాగే అది నడుస్తున్న machine పేర్లకు ప్రతిస్పందిస్తుంది. Container లో అది నడుస్తున్న machine అంటే ఆ container‌నే; కాబట్టి దాని hostname మీ hostname కాదు. halcyon.example.com గా వచ్చే request తిరస్కరించబడుతుంది, అలాగే తిరస్కరించిన host పేరును response చూపిస్తుంది. ఆ పేరును జోడించండి.

docker run -d --name halcyon -p 127.0.0.1:1420:1420 --restart unless-stopped \
  -e HALCYON_ALLOWED_HOSTS=halcyon.example.com \
  ghcr.io/halcyon-video/halcyon-video

ఈ value comma separated గా ఉంటుంది. .example.com వంటి ప్రారంభ dot subdomains కు కూడా సరిపోతుంది. all check ను ఆపివేస్తుంది. బయట నుంచి ఎవరూ చేరుకోలేని machine పై మాత్రమే all ఉపయోగించండి.

Store ను https:// ద్వారా అందించిన తర్వాత, login సమయంలో నమోదు చేసే Jellyfin address కూడా https:// అయి ఉండాలి. HTTPS page నుంచి plain http:// API call చేస్తే browser దాన్ని block చేస్తుంది, అలాగే console Mixed Content: The page at 'https://halcyon.example.com/' was loaded over HTTPS, but requested an insecure resource ను చదువుతుంది. Halcyon లో ఎలాంటి వివరణ లేకుండానే login విఫలమవుతుంది. రెండింటినీ TLS ద్వారా అందించండి, లేదా private network లో రెండింటినీ plain HTTP పై ఉంచండి.

తర్వాత authentication అమలు చేయాలి. Store Jellyfin credentials అడుగుతుంది. కాబట్టి URL కనుగొన్న వ్యక్తికి login screen కనిపిస్తుంది. ఒక feature ఈ పరిస్థితిని మారుస్తుంది. Settings, తరువాత Connection కింద Remote Play ను enable చేస్తే, మీ Jellyfin session server‌కు అందుతుంది. దాంతో /remote.html ను సందర్శించే వారికి మీ నిజమైన library యొక్క స్వంత instance లభిస్తుంది. ఈ feature ఉద్దేశం అదే. అంటే internet మరియు మీ films మధ్య నిలిచేది URL రహస్యంగా ఉండటమే. Remote Play enable చేస్తే, మొత్తం site ముందు single sign-on అమలు చేయడానికి self-hosted SSO gatewayగా Authentik ఉపయోగించండి, లేదా public hostname తొలగించి store ను wg-easy తో నిర్వహించే WireGuard tunnel ద్వారా చేరుకోండి.

దీనికి సంబంధించిన మరో రెండు విషయాలు ఉన్నాయి. Reverse proxy store traffic ను మాత్రమే మోస్తుంది. Remote Play stream WebRTC over UDP ద్వారా పనిచేస్తుంది, కాబట్టి అది HTTP proxy ద్వారా వెళ్లదు. అందువల్ల దీనికి 3478/udp పై ప్రత్యేక path అవసరం. Bundled TURN relay ఉపయోగించినప్పుడు 49200 నుంచి 49260/udp వరకు కూడా అవసరం. పై plain docker run ఎలాంటి volume ను నిల్వ చేయదు. అందువల్ల Remote Play seed docker rm తర్వాత నిలిచి ఉండదు. ఇదే కారణంగా Compose file /data వద్ద halcyon-data volume ను mount చేసి, REMOTE_PLAY_SEED ను /data/remote-play-seed.json గా set చేస్తుంది.

స్టోర్ సరిగా పనిచేయనప్పుడు ఏమి చేయాలి

Halcyon అవసరమైనప్పుడు మాత్రమే render చేస్తుంది. నిష్క్రియంగా ఉన్న స్టోర్ ఎలాంటి frameలను composite చేయదు. Window focus కోల్పోతే animation loop ఆగిపోతుంది. అందుకే తెరిచి ఉంచిన tab laptop batteryని అధికంగా వినియోగించదు. కేవలం పరిమిత సామర్థ్యంతో పనిచేసే machineకు ఇది సహాయపడుతుంది. అయితే స్టోర్‌ను అసలు render చేయలేని machineకు ఇది ఉపయోగపడదు.

అలాంటి clients కోసం 2.5D mode ఉంది. ఇది WebGL లేకుండా plain HTML మరియు CSSతో పనిచేస్తుంది. Raspberry Pi వంటి తక్కువ సామర్థ్య hardware కోసం దీన్ని రూపొందించారు. Page reload చేయకుండానే settings లేదా power menu నుంచి 3D మరియు 2.5D మధ్య మార్చవచ్చు. అందువల్ల ఒకే deviceలో రెండింటినీ పరీక్షించడానికి కొన్ని seconds చాలు. అయితే ఫలితాల గురించి వాస్తవికంగా ఉండాలి. రచయిత flat modeను ఇంకా అభివృద్ధిలో ఉన్న, పరిమితమైన రూపంగా వివరిస్తున్నారు. దీన్ని బలహీనమైన clients కోసం fallbackగా పరిగణించండి.

3D storeను నిర్వహించడానికి client సామర్థ్యం సరిపోకపోతే వైఫల్యం స్పష్టంగా కనిపిస్తుంది. Tab తనంతట తానే reload కావచ్చు. Browser lost WebGL contextని చూపించవచ్చు. ఇది సాధారణంగా shelves ఇంకా నిండుతున్న సమయంలో జరుగుతుంది. Libraryని తగ్గించడానికి బదులుగా ఆ deviceను 2.5Dకు మార్చండి.

చిత్రాన్ని digest కు pin చేసి, pull చేయడానికి ముందు తనిఖీ చేయండి

ఈ భాగాన్ని చాలా సీరియస్‌గా తీసుకోండి. v0.1.0 నుంచి v0.3.1 వరకు ఉన్న tags అన్నీ కొన్ని రోజుల వ్యవధిలోనే విడుదలయ్యాయి. v0.2.0 కోసం image push విఫలమైనందువల్ల మాత్రమే v0.2.1 ఉనికిలో ఉంది. Upstreamలో bug reports స్వాగతించబడతాయి, patches మాత్రం స్వీకరించబడవు. అందువల్ల release stream అనేది ఒక వ్యక్తి పని చేస్తున్న స్థితిపై ఆధారపడి ఉంది.

docker pull అలవాటుతో latest ను నడిపితే, సాధారణ మంగళవారం రోజున కూడా store మీ నియంత్రణ లేకుండా మారవచ్చు. digest తో pin చేయండి. మార్పు చెందలేని ఏకైక reference అదే.

docker buildx imagetools inspect ghcr.io/halcyon-video/halcyon-video:0.3.1

ఇది tag వెనుక ఉన్న digest ను చూపిస్తుంది. Tag స్థానంలో దానినే ఉపయోగించండి.

docker run -d --name halcyon -p 1420:1420 --restart unless-stopped \
  ghcr.io/halcyon-video/halcyon-video@sha256:747dcc821a3d2fa318b50e76024783c1835609047e84f502e23d021bc1898b20

10 August 2026 న ఆ digest 0.3.1 గా ఉంది. దాన్ని కాపీ చేయకుండా ప్రస్తుత digest ను మీరే చదవండి. మార్పు చేయడానికి ముందు release notes కూడా చదవండి. ఇక్కడ patch release లో fixes తో పాటు store layout మార్పులు కూడా ఉండవచ్చు.

FAQ

Halcyon కు నా VPSలో GPU అవసరమా?

సాధారణ వినియోగానికి అవసరం లేదు. Store ను browserలో three.js render చేస్తుంది. అందువల్ల rendering ను client machine నిర్వహిస్తుంది; container మాత్రం port 1420లో static files ను అందిస్తుంది. Remote Play దీనికి మినహాయింపు. ఇది serverలో headless Chromium ను నడిపి ఫలితాన్ని stream చేస్తుంది. మీరు hardware acceleration కోసం /dev/dri ను containerలో map చేయకపోతే, ఈ ప్రక్రియ CPUపై render అవుతుంది.

Halcyon ను public internetలో ఉంచవచ్చా?

Authentication వెనుక మాత్రమే ఉంచాలి. Store Jellyfin credentials ను అడుగుతుంది. అయితే Remote Play ను ప్రారంభిస్తే, మీ Jellyfin session serverకు అందుతుంది. అందువల్ల /remote.html ను load చేసే ఎవరైనా login లేకుండానే మీ నిజమైన library యొక్క instance ను పొందగలరు. దాని ముందు single sign on కలిగిన reverse proxy ఉంచండి. లేదా hostname ను public DNSలో ఉంచకుండా, VPN ద్వారా storeను చేరుకోండి.

Login చేసిన తర్వాత shelves ఎందుకు ఖాళీగా ఉన్నాయి?

Browser నేరుగా Jellyfin APIని call చేస్తుంది. అందువల్ల Jellyfin, VPS నుంచే కాకుండా browser నుంచీ కూడా reachable అయి ఉండాలి. Browser consoleను తెరవండి. blocked by CORS policy అంటే Jellyfin, Halcyon address నుంచి వచ్చిన requestను accept చేయడం లేదని అర్థం. Mixed Content message అంటే page HTTPSపై ఉండగా, మీరు నమోదు చేసిన Jellyfin address plain HTTPలో ఉందని అర్థం.

నాకు --network host అవసరమా?

Remote Play కోసం మాత్రమే అవసరం. WebRTC machine యొక్క నిజమైన addressను advertise చేయాలి. Docker bridge వెనుక container, మీ networkలోని ఏ phone కూడా చేరుకోలేని 172.x addressను మాత్రమే అందించగలదు. Browserలో storeను browse చేయడానికి -p 1420:1420 సరిపోతుంది. ఇది hostలో చాలా తక్కువ భాగాన్ని మాత్రమే బయటకు అందిస్తుంది.

ఏ image tagను ఉపయోగించాలి?

latest కంటే digestను pin చేయండి. docker buildx imagetools inspect ghcr.io/halcyon-video/halcyon-video:0.3.1 తో versionకు సంబంధించిన digestను చదవండి. ఆ digestను run చేసి, release notes చదివిన తర్వాత మాత్రమే మార్చండి. August 2026 నాటికి ప్రచురితమైన image linux/amd64 మాత్రమే. అందువల్ల arm64 host, clone నుంచి docker compose up -d తో build చేయాలి.