@elizaos/plugin-suno 1.0.6-alpha.4 → 2.0.11-beta.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,207 +1,81 @@
-@elizaos/plugin-suno
-
-A Suno AI music generation plugin for ElizaOS that enables AI-powered music creation and audio manipulation.
-
-OVERVIEW
-
-The Suno plugin integrates Suno AI's powerful music generation capabilities into ElizaOS, providing a seamless way to:
-- Generate music from text prompts with fine-tuned parameters
-- Create custom music with advanced control over style, tempo, and key
-- Extend existing audio tracks
-
-Original Plugin: https://github.com/gcui-art/suno-api?tab=readme-ov-file
-
-INSTALLATION
-
-    npm install @elizaos/plugin-suno
-
-QUICK START
-
-1. Register the plugin with ElizaOS:
-
-    import { sunoPlugin } from '@elizaos/plugin-suno';
-    import { Eliza } from '@elizaos/core';
-
-    const eliza = new Eliza();
-    eliza.registerPlugin(sunoPlugin);
-
-2. Configure the Suno provider with your API credentials:
-
-    import { sunoProvider } from '@elizaos/plugin-suno';
-
-    sunoProvider.configure({
-      apiKey: 'your-suno-api-key'
-    });
-
-FEATURES
-
-1. Generate Music (suno.generate-music)
-   Generate music using a text prompt with basic control parameters. This is ideal for quick music generation when you need less fine-grained control:
-
-   - Simple text-to-music generation
-   - Consistent output quality with default parameters
-   - Suitable for most common use cases
-
-    await eliza.execute('suno.generate-music', {
-      prompt: "An upbeat electronic dance track with energetic beats",
-      duration: 30,
-      temperature: 1.0,
-      topK: 250,
-      topP: 0.95,
-      classifier_free_guidance: 3.0
-    });
-
-2. Custom Music Generation (suno.custom-generate-music)
-   Create music with detailed control over generation parameters. Perfect for when you need precise control over the musical output:
-
-   - Fine-grained control over musical style and structure
-   - Reference-based generation using existing audio
-   - Control over musical attributes:
-     * Style: Specify genres like "classical", "electronic", "rock"
-     * Tempo: Set exact BPM (beats per minute)
-     * Key and Mode: Define musical key (e.g., "C") and mode ("major"/"minor")
-   - Advanced parameter tuning for generation quality
-
-    await eliza.execute('suno.custom-generate-music', {
-      prompt: "A melodic piano piece with soft strings",
-      duration: 30,
-      temperature: 0.8,
-      topK: 250,
-      topP: 0.95,
-      classifier_free_guidance: 3.0,
-      reference_audio: "path/to/reference.mp3",
-      style: "classical",
-      bpm: 120,
-      key: "C",
-      mode: "major"
-    });
-
-3. Extend Audio (suno.extend-audio)
-   Extend existing audio tracks to create longer compositions. Useful for:
-
-   - Lengthening existing music pieces
-   - Creating seamless loops
-   - Generating variations of existing tracks
-
-    await eliza.execute('suno.extend-audio', {
-      audio_id: "your-audio-id",
-      duration: 60
-    });
-
-Generation Parameters Explained:
-
-- temperature: Controls randomness in generation (0.0-1.0+)
-  * Lower values (0.1-0.5): More conservative, consistent output
-  * Higher values (1.0+): More creative, varied output
-
-- classifier_free_guidance: Controls how closely the output follows the prompt (1.0-20.0)
-  * Lower values: More creative interpretation
-  * Higher values: Stricter adherence to prompt
-
-- topK/topP: Control the diversity of the generation
-  * topK: Limits the number of tokens considered
-  * topP: Controls the cumulative probability threshold
-
-API REFERENCE
-
-SunoProvider Configuration
-The Suno provider accepts the following configuration options:
-
-    interface SunoConfig {
-      apiKey: string;
-    }
-
-Action Parameters:
-
-1. Generate Music (suno.generate-music)
-    interface GenerateParams {
-      prompt: string;
-      duration?: number;        // Duration in seconds
-      temperature?: number;     // Controls randomness
-      topK?: number;           // Top K sampling
-      topP?: number;           // Top P sampling
-      classifier_free_guidance?: number; // Guidance scale
-    }
-
-2. Custom Generate Music (suno.custom-generate-music)
-    interface CustomGenerateParams {
-      prompt: string;
-      duration?: number;
-      temperature?: number;
-      topK?: number;
-      topP?: number;
-      classifier_free_guidance?: number;
-      reference_audio?: string; // Path to reference audio file
-      style?: string;          // Musical style
-      bpm?: number;            // Beats per minute
-      key?: string;            // Musical key
-      mode?: string;           // Musical mode (e.g., "major", "minor")
-    }
-
-3. Extend Audio (suno.extend-audio)
-    interface ExtendParams {
-      audio_id: string;        // ID of the audio to extend
-      duration: number;        // Additional duration in seconds
-    }
-
-Response Type:
-    interface GenerationResponse {
-      id: string;             // Generated audio ID
-      status: string;         // Status of the generation
-      url?: string;          // URL to download the generated audio
-      error?: string;        // Error message if generation failed
-    }
-
-ERROR HANDLING
-
-The plugin includes built-in error handling for common scenarios:
-
-    try {
-      await eliza.execute('suno.generate', params);
-    } catch (error) {
-      if (error.code === 'SUNO_API_ERROR') {
-        // Handle API-specific errors
-      }
-      // Handle other errors
-    }
-
-EXAMPLES
-
-Creating a Pop Song:
-
-    const result = await eliza.execute('suno.generate-music', {
-      prompt: "Create a pop song with vocals, drums, and guitar",
-      duration: 180,
-      temperature: 1.0,
-      classifier_free_guidance: 3.5
-    });
-
-Creating a Custom Classical Piece:
-
-    const result = await eliza.execute('suno.custom-generate-music', {
-      prompt: "A classical piano sonata in the style of Mozart",
-      duration: 120,
-      temperature: 0.8,
-      style: "classical",
-      bpm: 120,
-      key: "C",
-      mode: "major"
-    });
-
-Extending an Existing Track:
-
-    const extended = await eliza.execute('suno.extend-audio', {
-      audio_id: "existing-track-id",
-      duration: 60
-    });
-
-LICENSE
-
-MIT
-
-SUPPORT
-
-For issues and feature requests, please open an issue on our GitHub repository.
-
----
-Built with ❤️ for ElizaOS
+# @elizaos/plugin-suno
+
+Suno AI music generation plugin for elizaOS. Enables Eliza agents to generate, custom-generate, and extend audio tracks via the Suno API.
+
+## What it does
+
+This plugin contributes a Suno HTTP client and a status provider (`SUNO_STATUS`) to the elizaOS agent runtime. Music generation is dispatched through the `MUSIC` umbrella action (provided by `@elizaos/plugin-music`); this plugin supplies the Suno-specific handler (`sunoGenerateMusicHandler`) that `plugin-music` mounts.
+
+Three subactions are supported:
+
+| Subaction | Endpoint | Required params |
+|---|---|---|
+| `generate` | `POST /generate` | `prompt` |
+| `custom_generate` | `POST /custom-generate` | `prompt`; optional: `style`, `bpm`, `key`, `mode`, `reference_audio` |
+| `extend` | `POST /extend` | `audio_id`, `duration` |
+
+The subaction is inferred from message text and params when not specified explicitly.
+
+## Requirements
+
+- A Suno API key (obtain at [suno.ai](https://suno.ai)).
+- `@elizaos/plugin-music` loaded alongside this plugin to expose the `MUSIC` action to agents.
+
+## Configuration
+
+Set the API key as an environment variable or in the agent character config:
+
+```
+SUNO_API_KEY=your-suno-api-key
+```
+
+The plugin auto-enables when `SUNO_API_KEY` is present, or when agent config sets:
+
+```json
+{
+  "media": {
+    "audio": {
+      "provider": "suno",
+      "mode": "own-key"
+    }
+  }
+}
+```
+
+## Generation parameters
+
+### `generate` and `custom_generate`
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `prompt` | string | (required) | Text description of the music to generate |
+| `duration` | number | 30 | Duration in seconds |
+| `temperature` | number | 1.0 | Randomness (higher = more creative) |
+| `topK` | number | 250 | Top-K sampling |
+| `topP` | number | 0.95 | Top-P sampling |
+| `classifier_free_guidance` | number | 3.0 | Prompt adherence strength |
+| `style` | string | — | Musical style (custom_generate only) |
+| `bpm` | number | — | Beats per minute (custom_generate only) |
+| `key` | string | — | Musical key, e.g. `"C"` (custom_generate only) |
+| `mode` | string | — | `"major"` or `"minor"` (custom_generate only) |
+| `reference_audio` | string | — | Reference audio path (custom_generate only) |
+
+### `extend`
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `audio_id` | string | Yes | ID of the existing track to extend |
+| `duration` | number | Yes | Additional seconds to add |
+
+## Response shape
+
+```ts
+interface GenerationResponse {
+  id: string;
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+  audio_url?: string;
+  error?: string;
+}
+```
+
+Responses larger than 4000 bytes are truncated before being returned to the agent context.

package/auto-enable.ts

@@ -0,0 +1,18 @@
+// Auto-enable check for @elizaos/plugin-suno.
+//
+// Plugin manifest entry-point — referenced by package.json's
+// `elizaos.plugin.autoEnableModule`. Keep this module light: env reads only,
+// no service init, no transitive imports of the full plugin runtime. The
+// auto-enable engine loads dozens of these per boot.
+import type { PluginAutoEnableContext } from '@elizaos/core';
+
+/**
+ * Enable when a Suno API key is in the environment, or when the user has
+ * explicitly selected Suno as the audio provider in own-key mode.
+ */
+export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
+    const apiKey = ctx.env.SUNO_API_KEY;
+    if (apiKey && apiKey.trim() !== '') return true;
+    const audio = ctx.config?.media?.audio;
+    return audio?.provider === 'suno' && audio?.mode === 'own-key';
+}

package/package.json

@@ -1,38 +1,80 @@
 {
-    "name": "@elizaos/plugin-suno",
-    "version": "1.0.6-alpha.4",
-    "description": "Suno AI Music Generation Plugin for Eliza",
-    "main": "dist/index.js",
-    "type": "module",
-    "types": "dist/index.d.ts",
-    "scripts": {
-        "build": "tsup --format esm",
-        "dev": "tsup --format esm --watch",
-        "lint": "echo \"Lint skipped for release\"",
-        "lint:check": "bun run lint",
-        "lint:fix": "biome check --apply src/",
-        "format": "biome format src/",
-        "format:fix": "biome format --write src/",
-        "test": "echo \"Tests skipped for release\"",
-        "typecheck": "echo \"Typecheck skipped for release\""
+  "name": "@elizaos/plugin-suno",
+  "version": "2.0.11-beta.7",
+  "description": "Suno AI Music Generation Plugin for Eliza",
+  "main": "dist/index.js",
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
-    "devDependencies": {
-        "@biomejs/biome": "1.5.3",
-        "@types/jest": "^27.0.0",
-        "@types/node": "^16.0.0",
-        "jest": "^27.0.0",
-        "tsup": "^8.3.5",
-        "typescript": "^5.0.0"
-    },
-    "agentConfig": {
-        "pluginType": "elizaos:client:1.0.0",
-        "pluginParameters": {
-            "apiKey": {
-                "type": "string",
-                "minLength": 1,
-                "description": "Your Suno API key for authentication.",
-                "optional": false
-            }
-        }
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "auto-enable.ts"
+  ],
+  "elizaos": {
+    "plugin": {
+      "autoEnableModule": "./auto-enable.ts",
+      "capabilities": [
+        "audio-generation"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsup --format esm",
+    "dev": "tsup --format esm --watch",
+    "lint": "bunx @biomejs/biome check .",
+    "lint:check": "bun run lint",
+    "lint:fix": "bunx @biomejs/biome check --write ./src",
+    "format": "bunx @biomejs/biome format --write ./src",
+    "format:check": "bunx @biomejs/biome format ./src",
+    "test": "vitest run --config vitest.config.ts",
+    "typecheck": "tsgo --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/node": "^22.19.17",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:client:1.0.0",
+    "pluginParameters": {
+      "apiKey": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Your Suno API key for authentication.",
+        "optional": false
+      }
     }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@elizaos/core": "2.0.11-beta.7"
+  },
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e"
 }

package/biome.json

@@ -1,41 +0,0 @@
-{
-  "$schema": "https://biomejs.dev/schemas/1.5.3/schema.json",
-  "organizeImports": {
-    "enabled": false
-  },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": true,
-      "correctness": {
-        "noUnusedVariables": "error"
-      },
-      "suspicious": {
-        "noExplicitAny": "error"
-      },
-      "style": {
-        "useConst": "error",
-        "useImportType": "off"
-      }
-    }
-  },
-  "formatter": {
-    "enabled": true,
-    "indentStyle": "space",
-    "indentWidth": 4,
-    "lineWidth": 100
-  },
-  "javascript": {
-    "formatter": {
-      "quoteStyle": "single",
-      "trailingCommas": "es5"
-    }
-  },
-  "files": {
-    "ignore": [
-      "dist/**/*",
-      "extra/**/*",
-      "node_modules/**/*"
-    ]
-  }
-}