kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/acestep/_settings.py

@@ -0,0 +1,82 @@
+"""ace-step capability config, read from the environment (``KIAPI_ACESTEP_``).
+
+Unset path settings are resolved under ``kiapi.core.app.get_user_data_dir()/acestep``.
+"""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings_manager import SettingsManager
+
+
+class AceStepSettings(BaseSettings):
+    """Settings for the ACE-Step isolated venv subprocess, checkpoints, and generation duration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="KIAPI_ACESTEP_",
+        extra="ignore",
+        protected_namespaces=(),
+    )
+
+    python_path: str | None = Field(
+        default=None,
+        title="ACE-Step Python executable",
+        description=(
+            "Python path for the dedicated venv where ACE-Step dependencies are installed.\n"
+            "When unset, kiapi uses the ACE-Step venv under the user data directory."
+        ),
+    )
+
+    project_root: str | None = Field(
+        default=None,
+        title="ACE-Step working directory",
+        description=(
+            "Directory where ACE-Step writes support files such as .cache/acestep.\n"
+            "When unset, kiapi uses an ACE-Step project directory under the user data directory."
+        ),
+    )
+
+    checkpoint_dir: str | None = Field(
+        default=None,
+        title="ACE-Step checkpoint directory",
+        description=(
+            "Directory containing checkpoint subdirectories such as "
+            "acestep-5Hz-lm-1.7B and acestep-v15-*.\n"
+            "When unset, kiapi uses the ACE-Step checkpoint directory under the "
+            "user data directory."
+        ),
+    )
+
+    llm_model: str = Field(
+        default="acestep-5Hz-lm-1.7B",
+        title="Shared LLM checkpoint name",
+        description=(
+            "Subdirectory name under checkpoint_dir for the ACE-Step language model checkpoint."
+        ),
+    )
+
+    ready_timeout_s: float = Field(
+        default=600.0,
+        title="Subprocess ready timeout seconds",
+        description=(
+            "Maximum seconds to wait for the ACE-Step subprocess to load models "
+            "and become ready."
+        ),
+    )
+
+    job_timeout_s: float = Field(
+        default=1200.0,
+        title="Generation job timeout seconds",
+        description="Maximum runtime seconds allowed for one ACE-Step generation job.",
+    )
+
+    max_duration: int = Field(
+        default=300,
+        title="Maximum generation seconds",
+        description=(
+            "Upper limit for music generation duration in seconds accepted in a request.\n"
+            "Longer values occupy the worker and keep memory resident for longer."
+        ),
+    )
+
+
+settings_manager = SettingsManager(AceStepSettings)

kiapi/capabilities/acestep/_views/ace_step_base.py

@@ -0,0 +1,61 @@
+"""Shared ACE-Step request fields (preset, mode, sampling overrides).
+
+Every acestep operation (generate/cover/repaint/extract) inherits these. The
+sampling overrides default to ``None`` so the chosen preset supplies its tuned
+value; set them only to deviate from the preset.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AceStepBase(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    model: str = Field(
+        default="xl-base",
+        pattern="^(xl-base|turbo)$",
+        description=(
+            "Preset (see GET /v1/audio/acestep/models). `xl-base` (default) = highest "
+            "quality (32 steps, CFG 7.0). `turbo` = fastest (8 steps, no CFG), good for "
+            "prototyping."
+        ),
+    )
+    mode: Literal["sync", "async"] = Field(
+        default="sync",
+        description=(
+            "`sync` waits for the track (504 on timeout); `async` returns 202 with a "
+            "job_id immediately — poll GET /v1/jobs/{job_id}."
+        ),
+    )
+    seed: int = Field(
+        default=-1,
+        description=(
+            "Random seed for reproducibility. `-1` picks a random seed; the same seed "
+            "with the same params reproduces the output. The resolved seed is recorded "
+            "in the result `params`."
+        ),
+    )
+    inference_steps: int | None = Field(
+        default=None,
+        description=(
+            "Override the preset's denoising step count (xl-base 32 / turbo 8). More "
+            "steps = higher quality, slower. Omit to use the preset default."
+        ),
+    )
+    guidance_scale: float | None = Field(
+        default=None,
+        description=(
+            "Override classifier-free guidance strength (xl-base default 7.0). Higher "
+            "follows the prompt more strictly. Ignored by `turbo`, which runs without "
+            "CFG. Omit to use the preset default."
+        ),
+    )
+    shift: float | None = Field(
+        default=None,
+        description=(
+            "Override the timestep schedule shift. 3.0 is correct; values near 1.0 "
+            "produce noisy output. Omit to use the preset default."
+        ),
+    )

kiapi/capabilities/acestep/_views/cover_params.py

@@ -0,0 +1,26 @@
+"""The complete contract for one ACE-Step cover run."""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class CoverParams(BaseModel):
+    task: Literal["cover"] = "cover"
+    model: str
+
+    src: str
+    src_audio: str
+    prompt: str
+    strength: float
+    duration: int | None
+    seed: int
+    inference_steps: int | None
+    guidance_scale: float | None
+    shift: float | None
+
+    def engine_params(self) -> dict:
+        return self.model_dump(exclude={"task", "model", "src"})
+
+    def meta_extra(self) -> dict:
+        return {"model": self.model, "src": self.src}

kiapi/capabilities/acestep/_views/cover_request.py

@@ -0,0 +1,49 @@
+"""ACE-Step cover request model."""
+
+from pydantic import Field
+
+from kiapi.core.file import FileRef
+
+from .ace_step_base import AceStepBase
+
+
+class CoverRequest(AceStepBase):
+    source: FileRef = Field(
+        description=(
+            "Source audio to re-style (Files-API file id, http(s) URL, or data URL). "
+            "POST the WAV to /v1/files first to get a file id."
+        )
+    )
+    prompt: str = Field(
+        description=(
+            "Target style description for the cover — the SOUND to move toward "
+            "(genre, instruments, mood, production)."
+        )
+    )
+    strength: float = Field(
+        default=0.7,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "How closely to follow the source structure, in 0..1. 0 = free / more "
+            "creative, 1 = strict / more faithful. 0.7 preserves structure well."
+        ),
+    )
+    duration: int | None = Field(
+        default=None,
+        ge=5,
+        le=300,
+        description="Output length in seconds (5-300). Omit to match the source length.",
+    )
+
+    def gen_params(self) -> dict:
+        return {
+            "prompt": self.prompt,
+            "source": self.source.model_dump(mode="json"),
+            "strength": self.strength,
+            "duration": self.duration,
+            "seed": self.seed,
+            "inference_steps": self.inference_steps,
+            "guidance_scale": self.guidance_scale,
+            "shift": self.shift,
+        }

kiapi/capabilities/acestep/_views/extract_params.py

@@ -0,0 +1,24 @@
+"""The complete contract for one ACE-Step source-separation stem run."""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class ExtractParams(BaseModel):
+    task: Literal["extract"] = "extract"
+    model: str
+
+    src: str
+    src_audio: str
+    target: str
+    seed: int
+    inference_steps: int | None
+    guidance_scale: float | None
+    shift: float | None
+
+    def engine_params(self) -> dict:
+        return self.model_dump(exclude={"task", "model", "src"})
+
+    def meta_extra(self) -> dict:
+        return {"model": self.model, "src": self.src, "target": self.target}

kiapi/capabilities/acestep/_views/extract_request.py

@@ -0,0 +1,33 @@
+"""ACE-Step extract request model."""
+
+from pydantic import Field
+
+from kiapi.core.file import FileRef
+
+from .ace_step_base import AceStepBase
+
+
+class ExtractRequest(AceStepBase):
+    source: FileRef = Field(
+        description=(
+            "Source audio to separate (Files-API file id, http(s) URL, or data URL). "
+            "POST the WAV to /v1/files first to get a file id."
+        )
+    )
+    targets: list[str] = Field(
+        default=["vocals", "drums", "bass", "other"],
+        description=(
+            "Stems to separate out, e.g. vocals / drums / bass / other (default: all "
+            "four). Each target becomes one artifact (file_id) within the single job."
+        ),
+    )
+
+    def gen_params(self) -> dict:
+        return {
+            "source": self.source.model_dump(mode="json"),
+            "targets": self.targets,
+            "seed": self.seed,
+            "inference_steps": self.inference_steps,
+            "guidance_scale": self.guidance_scale,
+            "shift": self.shift,
+        }

kiapi/capabilities/acestep/_views/generate_params.py

@@ -0,0 +1,25 @@
+"""The complete contract for one ACE-Step generate/text2music run."""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class GenerateParams(BaseModel):
+    task: Literal["text2music"] = "text2music"
+    model: str
+
+    prompt: str
+    lyrics: str
+    duration: int
+    lang: str
+    seed: int
+    inference_steps: int | None
+    guidance_scale: float | None
+    shift: float | None
+
+    def engine_params(self) -> dict:
+        return self.model_dump(exclude={"task", "model"})
+
+    def meta_extra(self) -> dict:
+        return {"model": self.model}

kiapi/capabilities/acestep/_views/generate_request.py

@@ -0,0 +1,54 @@
+"""ACE-Step generate (text2music) request model."""
+
+from pydantic import Field
+
+from .ace_step_base import AceStepBase
+
+
+class GenerateRequest(AceStepBase):
+    prompt: str = Field(
+        default="Modern J-Pop, 132 BPM, bright piano, emotional electric guitar, upbeat drums",
+        description=(
+            "Music style description — the SOUND (genre, tempo, instruments, mood, "
+            "production), not the lyric content. A narrative sentence works better "
+            "than a keyword list."
+        ),
+    )
+    lyrics: str = Field(
+        default="[Instrumental]",
+        description=(
+            "Lyrics, using [Verse 1]/[Chorus]/[Bridge]/… section tags at the start "
+            "of a line. Use `[Instrumental]` for a fully instrumental output. Match "
+            "the lyric length to `duration` — sparse lyrics over a long duration hurt "
+            "quality."
+        ),
+    )
+    duration: int = Field(
+        default=60,
+        ge=5,
+        le=300,
+        description=(
+            "Output length in seconds (5-300). Also capped server-side by the "
+            "acestep `max_duration` setting (422 if exceeded)."
+        ),
+    )
+    lang: str = Field(
+        default="ja",
+        description=(
+            "Vocal language as an ISO 639-1 code: ja / en / ko / zh / yue / es / fr / "
+            "de / …. `unknown` auto-detects (may reduce quality). Ignored for "
+            "`[Instrumental]` lyrics."
+        ),
+    )
+
+    def gen_params(self) -> dict:
+        return {
+            "prompt": self.prompt,
+            "lyrics": self.lyrics,
+            "duration": self.duration,
+            "lang": self.lang,
+            "seed": self.seed,
+            "inference_steps": self.inference_steps,
+            "guidance_scale": self.guidance_scale,
+            "shift": self.shift,
+        }

kiapi/capabilities/acestep/_views/repaint_params.py

@@ -0,0 +1,27 @@
+"""The complete contract for one ACE-Step repaint run."""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class RepaintParams(BaseModel):
+    task: Literal["repaint"] = "repaint"
+    model: str
+
+    src: str
+    src_audio: str
+    prompt: str
+    start: float
+    end: float
+    strength: float
+    seed: int
+    inference_steps: int | None
+    guidance_scale: float | None
+    shift: float | None
+
+    def engine_params(self) -> dict:
+        return self.model_dump(exclude={"task", "model", "src"})
+
+    def meta_extra(self) -> dict:
+        return {"model": self.model, "src": self.src}

kiapi/capabilities/acestep/_views/repaint_request.py

@@ -0,0 +1,51 @@
+"""ACE-Step repaint request model."""
+
+from pydantic import Field
+
+from kiapi.core.file import FileRef
+
+from .ace_step_base import AceStepBase
+
+
+class RepaintRequest(AceStepBase):
+    source: FileRef = Field(
+        description=(
+            "Source audio to repaint (Files-API file id, http(s) URL, or data URL). "
+            "POST the WAV to /v1/files first to get a file id."
+        )
+    )
+    prompt: str = Field(
+        description="Style description for the repainted section (the SOUND to apply)."
+    )
+    start: float = Field(
+        description="Start of the section to regenerate, in seconds from the track start."
+    )
+    end: float = Field(
+        default=-1,
+        description=(
+            "End of the section, in seconds. `-1` repaints from `start` to the end of "
+            "the track."
+        ),
+    )
+    strength: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "How aggressively to regenerate the section, in 0..1. 0 = subtle, blends "
+            "into the rest; 1 = aggressive."
+        ),
+    )
+
+    def gen_params(self) -> dict:
+        return {
+            "prompt": self.prompt,
+            "source": self.source.model_dump(mode="json"),
+            "start": self.start,
+            "end": self.end,
+            "strength": self.strength,
+            "seed": self.seed,
+            "inference_steps": self.inference_steps,
+            "guidance_scale": self.guidance_scale,
+            "shift": self.shift,
+        }

kiapi/capabilities/acestep/_views/track_params.py

@@ -0,0 +1,7 @@
+from .cover_params import CoverParams
+from .extract_params import ExtractParams
+from .generate_params import GenerateParams
+from .repaint_params import RepaintParams
+
+type TrackParams = GenerateParams | CoverParams | RepaintParams | ExtractParams
+"""Any one ACE-Step subprocess generation contract."""