@ziplayer/plugin 0.1.40 → 0.1.50

package/README.md

@@ -8,6 +8,7 @@ Official plugin bundle for ZiPlayer. It ships a set of ready‑to‑use source p
 - SoundCloudPlugin: search + stream SoundCloud tracks and sets
 - SpotifyPlugin: resolve tracks/albums/playlists, stream via fallbacks
 - TTSPlugin: Text‑to‑Speech playback from simple `tts:` queries
+- AttachmentsPlugin: handle Discord attachment URLs and direct audio file URLs
 
 ZiPlayer is an audio player built on top of `@discordjs/voice` and `discord.js`. This package provides sources; the core player
 lives in `ziplayer`.
@@ -28,15 +29,16 @@ npm install @zibot/zitts axios
 
 ```ts
 import { PlayerManager } from "ziplayer";
-import { YouTubePlugin, SoundCloudPlugin, SpotifyPlugin, TTSPlugin } from "@ziplayer/plugin";
+import { YouTubePlugin, SoundCloudPlugin, SpotifyPlugin, TTSPlugin, AttachmentsPlugin } from "@ziplayer/plugin";
 
 const manager = new PlayerManager({
 	plugins: [
-		// Order matters: put more specific handlers first (e.g., TTS)
+		// Order matters: put more specific handlers first (e.g., TTS, Attachments)
 		new TTSPlugin({ defaultLang: "en" }),
 		new YouTubePlugin(),
 		new SoundCloudPlugin(),
 		new SpotifyPlugin(),
+		new AttachmentsPlugin({ maxFileSize: 25 * 1024 * 1024 }), //25mb
 	],
 });
 
@@ -53,6 +55,9 @@ await player.play("https://www.youtube.com/playlist?list=...", requestedBy);
 // Speak with TTS
 await player.play("tts:en:Hello there!", requestedBy);
 
+// Play Discord attachment
+await player.play("https://cdn.discordapp.com/attachments/123/456/audio.mp3", requestedBy);
+
 // Handle events via the manager
 manager.on("trackStart", (plr, track) => {
 	plr.userdata?.channel?.send?.(`Now playing: ${track.title}`);
@@ -93,6 +98,7 @@ const sp = new SpotifyPlugin();
 ### TTSPlugin (Text‑to‑Speech)
 
 - Plays spoken audio from text using a lightweight Google TTS wrapper.
+- **Accurate duration analysis**: Generates sample audio to measure actual duration instead of estimating.
 - Supported query formats:
   - `tts: <text>`
   - `tts:<lang>:<text>` (e.g., `tts:vi:xin chao`)
@@ -101,6 +107,13 @@ const sp = new SpotifyPlugin();
 ```ts
 import { TTSPlugin } from "@ziplayer/plugin";
 const tts = new TTSPlugin({ defaultLang: "en", slow: false });
+
+// The plugin automatically analyzes TTS duration
+const result = await tts.search("tts:en:Hello world", "user123");
+console.log(`Duration: ${result.tracks[0].duration}s`); // Real duration from audio analysis
+console.log(`Language: ${result.tracks[0].metadata.language}`); // "en"
+console.log(`Slow mode: ${result.tracks[0].metadata.slowMode}`); // false
+
 await player.play("tts:en:1:good morning", requestedBy);
 ```
 
@@ -124,6 +137,29 @@ const tts = new TTSPlugin({
 });
 ```
 
+### AttachmentsPlugin
+
+- Handles Discord attachment URLs and direct audio file URLs.
+- Supports various audio formats (mp3, wav, ogg, m4a, flac, etc.).
+- **Audio metadata analysis**: Extracts duration, title, artist, album, bitrate, etc.
+- Includes file size validation and proper error handling.
+- Uses Range requests to efficiently analyze metadata without downloading entire files.
+
+```ts
+import { AttachmentsPlugin } from "@ziplayer/plugin";
+const attachments = new AttachmentsPlugin({
+	maxFileSize: 25 * 1024 * 1024, // 25MB
+	allowedExtensions: ["mp3", "wav", "ogg", "m4a", "flac"],
+	debug: true, // Enable to see metadata analysis process
+});
+
+// The plugin automatically analyzes audio metadata
+const result = await attachments.search("https://cdn.discordapp.com/attachments/123/456/song.mp3", "user123");
+console.log(`Duration: ${result.tracks[0].duration}s`); // Real duration from metadata
+console.log(`Title: ${result.tracks[0].title}`); // May be extracted from metadata
+console.log(`Artist: ${result.tracks[0].metadata.artist}`); // From metadata
+```
+
 ## Writing Your Own Plugin
 
 Plugins implement the `BasePlugin` contract from `ziplayer`:

package/dist/AttachmentsPlugin.d.ts

@@ -0,0 +1,192 @@
+import { BasePlugin, Track, SearchResult, StreamInfo } from "ziplayer";
+/**
+ * Configuration options for the AttachmentsPlugin.
+ */
+export interface AttachmentsPluginOptions {
+    /** Maximum file size in bytes (default: 25MB) */
+    maxFileSize?: number;
+    /** Allowed audio file extensions */
+    allowedExtensions?: string[];
+    /** Whether to enable debug logging */
+    debug?: boolean;
+}
+/**
+ * A plugin for handling Discord attachment URLs and local audio files.
+ *
+ * This plugin provides support for:
+ * - Discord attachment URLs (cdn.discordapp.com, media.discordapp.net)
+ * - Direct audio file URLs
+ * - Local file paths (if accessible)
+ * - Various audio formats (mp3, wav, ogg, m4a, flac, etc.)
+ * - File size validation
+ * - Audio metadata analysis (duration, title, artist, album, etc.)
+ * - Stream extraction from URLs
+ *
+ * @example
+ * const attachmentsPlugin = new AttachmentsPlugin({
+ *   maxFileSize: 25 * 1024 * 1024, // 25MB
+ *   allowedExtensions: ['mp3', 'wav', 'ogg', 'm4a', 'flac']
+ * });
+ *
+ * // Add to PlayerManager
+ * const manager = new PlayerManager({
+ *   plugins: [attachmentsPlugin]
+ * });
+ *
+ * // Search for attachment content
+ * const result = await attachmentsPlugin.search(
+ *   "https://cdn.discordapp.com/attachments/123/456/audio.mp3",
+ *   "user123"
+ * );
+ * const stream = await attachmentsPlugin.getStream(result.tracks[0]);
+ *
+ * @since 1.0.0
+ */
+export declare class AttachmentsPlugin extends BasePlugin {
+    name: string;
+    version: string;
+    private opts;
+    private readonly defaultAllowedExtensions;
+    /**
+     * Creates a new AttachmentsPlugin instance.
+     *
+     * @param opts - Configuration options for the attachments plugin
+     * @param opts.maxFileSize - Maximum file size in bytes (default: 25MB)
+     * @param opts.allowedExtensions - Allowed audio file extensions (default: common audio formats)
+     * @param opts.debug - Whether to enable debug logging (default: false)
+     *
+     * @example
+     * // Basic attachments plugin
+     * const attachmentsPlugin = new AttachmentsPlugin();
+     *
+     * // Custom configuration
+     * const customPlugin = new AttachmentsPlugin({
+     *   maxFileSize: 50 * 1024 * 1024, // 50MB
+     *   allowedExtensions: ['mp3', 'wav', 'ogg'],
+     *   debug: true
+     * });
+     */
+    constructor(opts?: AttachmentsPluginOptions);
+    /**
+     * Determines if this plugin can handle the given query.
+     *
+     * @param query - The URL or file path to check
+     * @returns `true` if the query is a Discord attachment URL or audio file URL, `false` otherwise
+     *
+     * @example
+     * plugin.canHandle("https://cdn.discordapp.com/attachments/123/456/audio.mp3"); // true
+     * plugin.canHandle("https://example.com/song.wav"); // true
+     * plugin.canHandle("youtube.com/watch?v=123"); // false
+     */
+    canHandle(query: string): boolean;
+    /**
+     * Validates if a URL is a valid Discord attachment URL or audio file URL.
+     *
+     * @param url - The URL to validate
+     * @returns `true` if the URL is valid and points to an audio file, `false` otherwise
+     *
+     * @example
+     * plugin.validate("https://cdn.discordapp.com/attachments/123/456/audio.mp3"); // true
+     * plugin.validate("https://example.com/song.wav"); // true
+     * plugin.validate("https://example.com/image.jpg"); // false
+     */
+    validate(url: string): boolean;
+    /**
+     * Creates a track from an attachment URL or file path.
+     *
+     * This method handles both Discord attachment URLs and direct audio file URLs.
+     * It extracts metadata from the URL and creates a track that can be played.
+     *
+     * @param query - The attachment URL or file path
+     * @param requestedBy - The user ID who requested the track
+     * @returns A SearchResult containing a single track
+     *
+     * @example
+     * // Discord attachment
+     * const result = await plugin.search(
+     *   "https://cdn.discordapp.com/attachments/123/456/audio.mp3",
+     *   "user123"
+     * );
+     *
+     * // Direct audio file URL
+     * const result2 = await plugin.search(
+     *   "https://example.com/song.wav",
+     *   "user123"
+     * );
+     */
+    search(query: string, requestedBy: string): Promise<SearchResult>;
+    /**
+     * Retrieves the audio stream from an attachment URL or file path.
+     *
+     * This method downloads the audio file from the URL and returns it as a stream.
+     * It handles various audio formats and provides proper error handling.
+     *
+     * @param track - The Track object to get the stream for
+     * @returns A StreamInfo object containing the audio stream
+     * @throws {Error} If the URL is invalid, file is too large, or download fails
+     *
+     * @example
+     * const track = {
+     *   id: "attachment-123",
+     *   title: "audio.mp3",
+     *   url: "https://cdn.discordapp.com/attachments/123/456/audio.mp3",
+     *   ...
+     * };
+     * const streamInfo = await plugin.getStream(track);
+     * console.log(streamInfo.type); // "arbitrary"
+     * console.log(streamInfo.stream); // Readable stream
+     */
+    getStream(track: Track): Promise<StreamInfo>;
+    /**
+     * Provides a fallback by attempting to re-download the file.
+     *
+     * @param track - The Track object to get a fallback stream for
+     * @returns A StreamInfo object containing the fallback audio stream
+     * @throws {Error} If fallback download fails
+     */
+    getFallback(track: Track): Promise<StreamInfo>;
+    /**
+     * Checks if a file path or URL is an audio file based on extension.
+     */
+    private isAudioFile;
+    /**
+     * Extracts the file extension from a path or URL.
+     */
+    private getFileExtension;
+    /**
+     * Extracts filename from a URL or path.
+     */
+    private extractFilename;
+    /**
+     * Checks if a URL is a Discord attachment URL.
+     */
+    private isDiscordAttachment;
+    /**
+     * Generates a unique track ID for a given URL.
+     */
+    private generateTrackId;
+    /**
+     * Simple hash function for generating IDs.
+     */
+    private simpleHash;
+    /**
+     * Determines the appropriate stream type based on content type and file extension.
+     */
+    private getStreamType;
+    /**
+     * Formats bytes into a human-readable string.
+     */
+    private formatBytes;
+    /**
+     * Analyzes audio metadata to extract duration and other information.
+     *
+     * @param url - The URL to analyze
+     * @returns Promise containing duration in seconds and metadata
+     */
+    private analyzeAudioMetadata;
+    /**
+     * Debug logging helper.
+     */
+    private debug;
+}
+//# sourceMappingURL=AttachmentsPlugin.d.ts.map

package/dist/AttachmentsPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttachmentsPlugin.d.ts","sourceRoot":"","sources":["../src/AttachmentsPlugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAKvE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,sCAAsC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAChD,IAAI,SAAiB;IACrB,OAAO,SAAW;IAElB,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAsE;IAE/G;;;;;;;;;;;;;;;;;;OAkBG;gBACS,IAAI,CAAC,EAAE,wBAAwB;IAS3C;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IA8BjC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA0EvE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;IA0DlD;;;;;;OAMG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;IAKpD;;OAEG;IACH,OAAO,CAAC,WAAW;IAKnB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,OAAO,CAAC,UAAU;IAUlB;;OAEG;IACH,OAAO,CAAC,aAAa;IAgBrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAQnB;;;;;OAKG;YACW,oBAAoB;IA2ElC;;OAEG;IACH,OAAO,CAAC,KAAK;CAKb"}