iՇ2%SrSSKrSSKrSSKrSSKrSSKrSSKJrJrJ r J r SSK J r SSK Jr SSSSSSSSSSSS S S S .r\ \\4\S 'S\ 4SjrS\ S\4SjrS\S\\4SjrS\S\\4SjrSLS\S\4SjjrSMS\S\ S\\SS4SjjrS\S\ SS4SjrSNS\S\ S\\S\\S\ \\44 SjjrSrSS S!S"S#S$S%S&S'S(S). r\ \\4\S*'/S+QrS,rS-S.0r \ \\4\S/'S0r!S\ 4S1jr"SMS2\\S\ 4S3jjr#S4\ S\4S5jr$SMS6\\ S\4S7jjr%SMS\S6\\ S\4S8jjr&S\ \\44S9jr'SOS6\\ S:\S\\S\\S\ \\44 S;jjr(SOS\S6\\ S:\S\\S\\S\ \\44 S<jjr)SPS6\\ S:\S\\S\ \\\44S=jjr*SQS6\\ S\\S\\S\ \\44S>jjr+SRS\\S6\\ S\\S\\S\ \\44 S?jjr,SQS\S6\\ S\\S\\S\ \\44 S@jjr-S\\4SAjr.SBSCSD\\S\ 4SEjr/SMSD\S6\\ S\4SFjjr0SOSD\S6\\ S:\S\\S\\S\ \\44 SGjjr1SRSD\\S6\\ S\\S\\S\ \\44 SHjjr2SIr3SJr4\5SK:Xa\Rl"\4"55 gg)Sz ACE-Step Model Downloader This module provides functionality to download models from HuggingFace Hub or ModelScope. It supports automatic downloading when models are not found locally, with intelligent fallback between download sources. N)OptionalListDictTuple)Path)loggerturbosftbasexl_basexl_sftxl_turbo)acestep-v15-turboacestep-v15-sftacestep-v15-basezacestep-v15-base-sft-fix-instacestep-v15-turbo-shift1acestep-v15-turbo-shift3acestep-v15-turbo-continuousz!acestep-v15-turbo-fix-inst-shift3z+acestep-v15-turbo-fix-inst-shift-continuousz(acestep-v15-turbo-fix-inst-shift-dynamiczacestep-v15-turbo-rlacestep-v15-xl-baseacestep-v15-xl-sftacestep-v15-xl-turbo_CHECKPOINT_TO_VARIANTreturncV[[5R5RS- $)zHGet the acestep/models/ directory (authoritative source for model code).models)r__file__resolveparentO/mnt/workspace/acestep.cpp/tests/../../ACE-Step-1.5/acestep/model_downloader.py_get_models_source_dirr".s > ! ! # * *X 55r filepathc^[R"5n[US5m[U4SjS5HnUR U5 M SSS5 UR 5$!,(df  UR 5$=f)z*Compute SHA-256 hash of a file's contents.rbc&>TRS5$)Ni )read)fsr!_file_hash..7s !&&,r r N)hashlibsha256openiterupdate hexdigest)r#hchunkr(s @r! _file_hashr33sbA h .4E HHUO5  ;;=   ;;=s )A$$ B model_namec [RU5nUc/$[5U- nUR5(d/$[ U[ 5(a [ U5nX- n/nURS5HnURS:XaMXFR- nUR5(dURUR5 MU[U5[U5:wdMoURUR5 M U$)a? Compare .py files in acestep/models/{variant}/ with those in the checkpoint directory. Args: model_name: Checkpoint directory name (e.g. "acestep-v15-turbo") checkpoints_dir: Path to the checkpoints root directory Returns: List of filenames that differ (empty list if all match or model_name is unknown) *.py __init__.py) rgetr"exists isinstancestrrglobnameappendr3)r4checkpoints_dirvariant source_dir target_dir mismatchedsrc_filedst_files r!_check_code_mismatchrF<s%((4G ')G3J      /3''/ -JJOOF+ ==M )  -    hmm ,  !Z%9 9   hmm ,, r c~[RU5nUc/$[5U- nUR5(d[R "SU35 /$[ U[5(a [U5nX- nUR5(d[R "SU35 /$/nURS5HznURS:XaMXFR- n[R"Xg5 URUR5 [R"SURSU35 M| U$)af Copy .py files from acestep/models/{variant}/ into the checkpoint directory, overwriting the HuggingFace-downloaded versions. Args: model_name: Checkpoint directory name (e.g. "acestep-v15-turbo") checkpoints_dir: Path to the checkpoints root directory Returns: List of filenames that were synced (empty if model_name is unknown or no source) z)[Model Sync] Source directory not found: z)[Model Sync] Target directory not found: r6r7z[Model Sync] Synced  -> )rr8r"r9rwarningr:r;rr<r=shutilcopy2r>debug)r4r?r@rArBsyncedrDrEs r!_sync_model_code_filesrN`s%((4G ')G3J     B:,OP /3''/ -J     B:,OP FOOF+ ==M )  - X( hmm$ +HMM?$xjIJ , Mr timeoutcXSSKnURURUR5nURU5 UR S5 UR 5 g!UR UR[4a UR 5 gf=f!UR 5 f=f)z Check if Google is accessible (to determine HuggingFace vs ModelScope). Args: timeout: Connection timeout in seconds Returns: True if Google is accessible, False otherwise rN)zwww.google.comiTF) socketAF_INET SOCK_STREAM settimeoutconnectcloserOerrorOSError)rOrQsocks r!_can_access_googlerZs ==);); (G:H G; !G6+G;,G>0H6G;;G>>HzACE-Step/Ace-Step1.5zACE-Step/acestep-5Hz-lm-0.6BzACE-Step/acestep-5Hz-lm-4Bz!ACE-Step/acestep-v15-turbo-shift3zACE-Step/acestep-v15-sftzACE-Step/acestep-v15-basez!ACE-Step/acestep-v15-turbo-shift1z%ACE-Step/acestep-v15-turbo-continuouszACE-Step/acestep-v15-xl-basezACE-Step/acestep-v15-xl-sftzACE-Step/acestep-v15-xl-turbo) zacestep-5Hz-lm-0.6Bzacestep-5Hz-lm-4BrrrrrrrrSUBMODEL_REGISTRY)rvaezQwen3-Embedding-0.6Bacestep-5Hz-lm-1.7Br{scragvaezscragnog/Ace-Step-1.5-ScragVAE VAE_REGISTRYofficialc[RRS5nU(a[U5R 5$[[R "55$)aGet the project root directory. Returns the directory set by the ``ACESTEP_PROJECT_ROOT`` environment variable when present, otherwise the current working directory. Using the working directory (rather than ``__file__``) keeps the checkpoints folder next to where the user launched the process, regardless of whether the package was installed via ``pip install .`` or run from source. ACESTEP_PROJECT_ROOT)osenvironr8rrgetcwd)env_roots r!get_project_rootrIs>zz~~45HH~%%''  r custom_dircU(a [U5$[RRS5nU(a'[U5R 5R 5$[ 5S- $)uhGet the checkpoints directory path. Resolution order: 1. *custom_dir* argument (passed programmatically) 2. ``ACESTEP_CHECKPOINTS_DIR`` environment variable – allows users to share a single model directory across multiple ACE-Step installations, avoiding duplicate downloads that waste disk space. 3. ``/checkpoints`` (original default) ACESTEP_CHECKPOINTS_DIR checkpoints)rrrr8 expanduserrr)renv_dirs r!get_checkpoints_dirrXsRJjjnn67GG}'')1133   --r model_pathc^^SnTR5(dg[U4SjU55$)zReturn whether a model directory contains at least one weights artifact. Args: model_path: Candidate model directory path. Returns: `True` when a known model weights file exists in the directory. )zmodel.safetensorszmodel.safetensors.index.jsonzpytorch_model.binzpytorch_model.bin.index.jsonz#diffusion_pytorch_model.safetensorsz.diffusion_pytorch_model.safetensors.index.jsonzdiffusion_pytorch_model.binz&diffusion_pytorch_model.bin.index.jsonFc3J># UHnTU- R5v M g7fN)r9).0filenamers r! *_contains_model_weights..s$Q@PH X%--//@Ps #)is_dirany)rweight_filenamess` r!_contains_model_weightsrjs1       Q@PQ QQr r?cUc [5nO [U[5(a [U5n[HnX- n[ U5(aM g g)z Check if the main model components exist in the checkpoints directory. Returns: True if all main model components contain weights, False otherwise. FT)rr:r;rMAIN_MODEL_COMPONENTSr)r? componentcomponent_paths r!check_main_model_existsrsN-/ OS ) )/* (4&~66+ r cU(d[R"S5 gUc [5nO [U[5(a [ U5nX- n[ U5$)z Check if a specific model exists in the checkpoints directory. Args: model_name: Name of the model to check checkpoints_dir: Custom checkpoints directory (optional) Returns: True if the model exists, False otherwise. z;[check_model_exists] Empty model_name; treating as missing.F)rrIrr:r;rr)r4r?rs r!check_model_existsrsO TU-/ OS ) )/ -J ": ..r c"S[0[EnU$)zo List all available models for download. Returns: Dictionary mapping local names to HuggingFace repo IDs. main)MAIN_MODEL_REPOry)rs r!list_available_modelsrs  F Mr forcecUc [5nO [U[5(a [U5nUR SSS9 U(d[ U5(aSSU34$[ S[S35 [ SU35 [ S5 [[XU5upEU(aI[H?nU[;dM[X`5nU(dM#[R"SUS U35 MA XE4$) a/ Download the main ACE-Step model from HuggingFace or ModelScope. The main model includes: - acestep-v15-turbo (default DiT model) - vae (audio encoder/decoder) - Qwen3-Embedding-0.6B (text encoder) - acestep-5Hz-lm-1.7B (default LM model) Args: checkpoints_dir: Custom checkpoints directory (optional) force: Force re-download even if model exists token: HuggingFace token for private repos (optional) prefer_source: Preferred download source ("huggingface", "modelscope", or None for auto-detect) Returns: Tuple of (success, message) TrlzMain model already exists at zDownloading main model from ... Destination: z>This may take a while depending on your internet connection...'[Model Download] Synced code files for : )rr:r;rrqrprintrrxrrrNrrd)r?rr]rjsuccessmsgrrMs r!download_main_modelrs0-/ OS ) )/$6 ,_==4_4EFFF ((9 => M/* +, JK#?OMZLG.I22/ K6KK"I)TVW]V^ _` / <r c2U[;a-SR[R55nSSUSU34$Uc [5nO [ U[ 5(a [ U5nURSSS9 X- nU(dUR5(a SSUSU34$[Un[S US US 35 [S U35 [XvX45upU(a8U[;a.[X5n U (a[R"S USU 35 X4$)a Download a specific sub-model from HuggingFace or ModelScope. Args: model_name: Name of the model to download (must be in SUBMODEL_REGISTRY) checkpoints_dir: Custom checkpoints directory (optional) force: Force re-download even if model exists token: HuggingFace token for private repos (optional) prefer_source: Preferred download source ("huggingface", "modelscope", or None for auto-detect) Returns: Tuple of (success, message) , FzUnknown model 'z'. Available models: TrlzModel '' already exists at z Downloading z from rrrr)ryjoinkeysrr:r;rrqr9rrxrrNrrd) r4r?rr]rj availablerr[rrrMs r!download_submodelrs%(**II/4467  |3H TTT-/ OS ) )/$6 -J Z&&((wzl*>zlKKK +G L F7)3 78 M* &'#7MLG:!77' D  KKA*RPVxX Y <r c*Uc [5nO [U[5(a [U5n/nSn[ XU5upVUR U5 U(dSn[ H-n[XpX5upVUR U5 U(aM+SnM/ XC4$)a Download all available models. Args: checkpoints_dir: Custom checkpoints directory (optional) force: Force re-download even if models exist token: HuggingFace token for private repos (optional) Returns: Tuple of (all_success, list of messages) TF)rr:r;rrr>ryr)r?rr]messages all_successrrr4s r!download_all_modelsr!s -/ OS ) )/HK'uELG OOC  ( (eS wK (   r cUc [5n[U5(ag[S5 [S5 [S5 [XUS9$)a Ensure the main model is available, downloading if necessary. This function is designed to be called during initialization. It will only download if the model doesn't exist. Args: checkpoints_dir: Custom checkpoints directory (optional) token: HuggingFace token for private repos (optional) prefer_source: Preferred download source ("huggingface", "modelscope", or None for auto-detect) Returns: Tuple of (success, message) )TzMain model is available= ============================================================z4Main model not found. Starting automatic download...============================================================= r]rj)rrrr)r?r]rjs r!ensure_main_modelrIsF&-///. / @A / = YYr cUc[nUc [5nO [U[5(a [ U5n[ X5(aSSUS34$U[ ;aP[ H?nSUR5;dMUR5UR5;dM=Un O SSU34$[S5 [SUS35 [S 5 [XX#S 9$) a Ensure an LM model is available, downloading if necessary. Args: model_name: Name of the LM model (defaults to DEFAULT_LM_MODEL) checkpoints_dir: Custom checkpoints directory (optional) token: HuggingFace token for private repos (optional) prefer_source: Preferred download source ("huggingface", "modelscope", or None for auto-detect) Returns: Tuple of (success, message) Tz LM model '' is availablelmFzUnknown LM model: r+' not found. Starting automatic download...rr) DEFAULT_LM_MODELrr:r;rrrylowerrr)r4r?r]rj known_models r!ensure_lm_modelris$% -/ OS ) )/*66z*^<<<**,K{((**z/?/?/A[EVEVEX/X( - .zl;; ; / Jzl"M NO / Z ccr cBUc [5nO [U[5(a [U5n[ X5(aSSUS34$US:Xa [ XU5$U[ ;a/[S5 [SUS35 [S5 [XX#S9$U(dg S S U34$) an Ensure a DiT model is available, downloading if necessary. Args: model_name: Name of the DiT model checkpoints_dir: Custom checkpoints directory (optional) token: HuggingFace token for private repos (optional) prefer_source: Preferred download source ("huggingface", "modelscope", or None for auto-detect) Returns: Tuple of (success, message) Tz DiT model 'rrrrrr)FzEUnknown DiT model: '' (pass None for default or choose a valid model)FzUnknown DiT model: ) rr:r;rrrryrr)r4r?r]rjs r!ensure_dit_modelrs$-/ OS ) )/*66{:,n===(( GG&& o J<'RST o Egg ] ' |4 44r c8[/[R5Q$)z7Return all selectable VAE variant ids (official first).)DEFAULT_VAE_VARIANTr}rrr r!list_available_vae_variantsrs  6,"3"3"5 66r checkpoint_dirz str | Path vae_variantc B[U[5(a [U5nU(dUS- $[RR U5(a [U5$U[ :XaUS- $U[;aX- $[SUSSR[5535e)aResolve a VAE variant id (or absolute path) to its on-disk directory. Args: checkpoint_dir: Root checkpoints directory. vae_variant: Variant id (``"official"`` or a key in ``VAE_REGISTRY``) or an absolute filesystem path. ``None`` / ``""`` is treated as ``"official"``. Returns: Absolute path of the VAE checkpoint directory. Raises: ValueError: If ``vae_variant`` is not recognized. rzUnknown VAE variant ''. Available: r) r:r;rrpathisabsrr} ValueErrorrr)rrs r!resolve_vae_pathrs.#&&n- %% ww}}[!!K  ))%%l"++   }N 9902 3 4 6 r cUc [5nO [U[5(a [U5n[ X5n[ U5$![ a gf=f)z=Return whether the requested VAE variant has weights on disk.F)rr:r;rrrr)rr?rs r!check_vae_existsrsW-/ OS ) )/= #4 (( s A AAcU[:Xa SS[S34$U[;a6SR[R55=(d SnSSUSU34$Uc [ 5nO [ U[ 5(a [U5nURSSS 9 X- nU(d[U5(a SSUS U34$[Un[S US US 35 [SU35 [XvX45$)uDownload a community VAE variant into ``//``. The bundled ``"official"`` VAE is *not* downloaded here — it ships with the main model and is fetched by ``download_main_model``. F VAE variant 'z?' ships with the main model; use download_main_model() instead.rz(none)rrTrlrzDownloading VAE 'z' from rr) rr}rrrr:r;rrqrrrx)rr?rr]rjr target_pathr[s r! download_vaers))/011 1  ,&IIl//12>h -k]. TTT-/ OS ) )/$6!/K ,[99}[M1Ek]SSS;'G k]''# >? M+ '( 7 FFr cU(a U[:Xa [XU5$Uc [5nO [U[5(a [ U5n[ X5(aSSUS34$[RRU5(a0[ U5nUR5(dSSUS34$SSUS34$[S5 [SUS 35 [S 5 [XX#S 9$) aEnsure the requested VAE variant is on disk, downloading if needed. For ``"official"`` (or ``None``) this defers to ``ensure_main_model`` since the bundled VAE travels with the main model. For registered community variants this calls ``download_vae`` when the directory is missing. TrrFz VAE path 'z' does not exist.zN' does not contain VAE weights (expected diffusion_pytorch_model.safetensors).rrrr) rrrr:r;rrrrrr9rr)rr?r]rjrs r!ensure_vae_modelrs +)<< GG-/ OS ) )/ 55}[M@@@  ww}}[!!K {{}}J{m3DEE E &> >   / M+&Q RS /  E __r c[S5 [S5 [S5 [S5 [S[35 [S5 [S5 [R5H,upSUR 5;dM[S US U35 M. [S 5 [R5H,upSUR 5;dM[S US U35 M. [ (aK[S 5 [S [35 [ R5Hup[S US U35 M [S5 g)z)Print formatted list of available models.z Available Models for Download:z<============================================================zB Supported Sources: HuggingFace Hub <-> ModelScope (auto-fallback)z [Main Model]z main -> zM Contains: vae, Qwen3-Embedding-0.6B, acestep-v15-turbo, acestep-5Hz-lm-1.7Bz [Optional LM Models]rz rHz [Optional DiT Models]z [Optional VAEs]z official -> bundled in rN)rrryitemsrr})r=repos r!print_model_listrCs ,- (O OP  J' () YZ "#'--/  4::<  BtfD' (0 #$'--/  tzz| # BtfD' (0| !" )/):;<&,,.JD BtfD' (/ /r c[R"S[RSS9nURSS[SS9 URSS S S S 9 URS SS SS 9 URSS[SSS9 URSSS SS 9 URSS[SSS9 URSS SS 9 UR 5nUR (a [5 gUR(a[UR5O [5n[SU35 UR(aA[X!RUR5up4UHn[U5 M U(aS$S$UR(GaURS :Xa#[!X!RUR5up5OUR[";aUR$(dP['U5(d@[S!5 [!X!RUR5upg[U5 U(dg[)URX!RUR5up5O$[S"UR35 [S#5 g[U5 U(aS$S$[S$5 [!X!RUR5up5[U5 U(a[S%5 [S&U35 U(aS$S$)'z&CLI entry point for model downloading.zMDownload ACE-Step models with automatic fallback (HuggingFace <-> ModelScope)a Examples: acestep-download # Download main model (includes LM 1.7B) acestep-download --all # Download all available models acestep-download --model acestep-v15-sft # Download a specific model acestep-download --list # List all available models Network Detection: Automatically detects network environment and chooses the best download source: - Google accessible -> HuggingFace (fallback to ModelScope) - Google blocked -> ModelScope (fallback to HuggingFace) Shared checkpoints directory: Set ACESTEP_CHECKPOINTS_DIR to share models across multiple installations: export ACESTEP_CHECKPOINTS_DIR=~/ace-step-models Alternative using huggingface-cli: huggingface-cli download ACE-Step/Ace-Step1.5 --local-dir ./checkpoints huggingface-cli download ACE-Step/acestep-5Hz-lm-0.6B --local-dir ./checkpoints/acestep-5Hz-lm-0.6B ) descriptionformatter_classepilogz--modelz-mz?Specific model to download (use --list to see available models))typehelpz--allz-a store_truezDownload all available models)actionrz--listz-lzList all available modelsz--dirz-dNz5Custom checkpoints directory (default: ./checkpoints))rdefaultrz--forcez-fz&Force re-download even if model existsz--tokenz-tz#HuggingFace token for private reposz --skip-mainzCSkip downloading the main model (only download specified sub-model)rzCheckpoints directory: rz5Main model not found. Downloading main model first...zUnknown model: z"Use --list to see available modelszHDownloading main model (includes vae, text encoder, DiT, and LM 1.7B)...z Download complete!zModels are available at: )argparseArgumentParserRawDescriptionHelpFormatter add_argumentr; parse_argslistrdirrrallrrr]modelrry skip_mainrr)parserargsr?rrr main_successmain_msgs r!rr`s  $ $c << F2 4  N   ,  $ (    D   4 5  4  2    R    D yy8>*A/*R*RMN)<_jjZ^ZdZd)e& h#,TZZ**VZV`V`aLGS ODJJ<0 1 6 7 c q"" TU' DJJOLG #J $% )/):;<1Qr __main__)g@r)NN)NFNN)NFN)NNN)NNNN)7__doc__rsysr+rJrtypingrrrrpathlibrlogururrr;__annotations__r"r3rFrNfloatboolrZrerirxrryrrr}rrrrrrrrrrrrrrrrrrrr__name__exitrr r!rs  ..!%* ' '$+)03:07#$"&#*S#X*66 #!S!d3i!H%s%S %X2   C= 8  6 #' B( B(B( C=B(C= B(  49 B(R) :5 C13 C$K97;%4S>")0  d38n ! $ .HSM.T.$RRR0Xd^t&/3/$/SW/. tCH~ '+#' 0d^0 0 C=0C= 0  49 0j'+#' 11d^1 1 C= 1 C= 1  49 1j'+%!d^%! %! C=%! 4c? %!R'+#'Zd^Z C=ZC=Z 49 ZB!%&*#' +d +dd^+d C=+dC= +d  49 +d`'+#' '5'5d^'5 C='5C= '5  49 '5T7T#Y7 \ RV> )# ) )RV )'+#' #G#Gd^#G #G C= #G C= #G  49 #GN"&&*#' (`#(`d^(` C=(`C= (`  49 (`V:tn zHHTVr