Hum Song Skill

This is the lightweight hum-song skill. Its job is to guide the user to download, install, configure, and run the full hum-song agent.

The full agent lives in the same repository after download. It contains the API, CLI, provider orchestration, tests, and OpenClaw/Hermes agent metadata under agents/.

When To Use

Use this skill when a user wants to:

• Install the hum-song agent into OpenClaw or Hermes.
• Turn a humming recording into a generated song, but the full agent is not installed yet.
• Check whether git, node, and pnpm are available before installing.
• Start the local hum-song API and submit audio through the agent CLI.
• Understand the required Mureka/DeepSeek/ElevenLabs provider configuration.

Install Flow

If the current machine does not have the agent yet, guide the user through:

git clone https://github.com/harrylabsj/hum-song.git
cd hum-song
pnpm install
bash scripts/install.sh --both
pnpm verify

Default installation targets:

OpenClaw: ~/.openclaw/workspace/skills/hum-song
Hermes:   ~/.hermes/skills/creative/hum-song

Use targeted installs when needed:

bash scripts/install.sh --openclaw
bash scripts/install.sh --hermes

Use dry-run first if the user is unsure:

bash scripts/install.sh --both --dry-run

Use --force only when the user confirms replacing an existing install target:

bash scripts/install.sh --both --force

Start The Agent

From the downloaded repo:

cd hum-song
cp .env.example .env
pnpm build
pnpm serve

Then submit a humming file:

node scripts/hum-song.mjs submit \
  --audio ./humming.m4a \
  --theme "rainy night" \
  --genre pop \
  --language Chinese \
  --duration 60 \
  --wait \
  --format markdown

After package installation, the same command is available as:

hum-song submit --audio ./humming.m4a --theme "rainy night" --wait --format markdown

Provider Configuration

Mock providers work out of the box for smoke tests.

For real providers, edit .env:

LYRICS_PROVIDER=deepseek
DEEPSEEK_API_KEY=...

MUSIC_PROVIDER=mureka
MUREKA_API_KEY=...
MUREKA_CREATE_URL=...
MUREKA_STATUS_URL_TEMPLATE=...

VOICE_PROVIDER=elevenlabs
ELEVENLABS_API_KEY=...
ALLOW_VOICE_CONVERSION=false

Voice conversion is opt-in. Only set ALLOW_VOICE_CONVERSION=true after the user understands the consent requirement. The CLI also requires --voice-consent for --voice-mode preserve|clone.

Agent Boundary

• This skill is an installer and launcher guide.
• The full runtime behavior is in agents/hum-song-agent.yaml and scripts/hum-song.mjs.
• Do not ask for unnecessary personal data.
• Do not process voice conversion unless the user explicitly consents.
• Do not claim to reproduce a living artist's voice or copyrighted soundalike.

Verification

Before claiming installation is ready:

node scripts/hum-song.mjs --help
pnpm verify
pnpm test
pnpm typecheck