@feralfile/cli 1.3.0 → 1.4.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "description": "CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)",
     "repository": {
         "type": "git",

package/dist/src/ai-orchestrator/index.js

@@ -68,16 +68,19 @@ function inferToolCallFromContent(content, iterationCount) {
                 typeof parsed === 'object' &&
                 parsed.requirement &&
                 typeof parsed.requirement === 'object' &&
-                typeof parsed.duration === 'number') {
+                (parsed.duration === undefined || typeof parsed.duration === 'number')) {
+                // duration is optional: absent means auto timing (DP-1 §4.1), so the
+                // synthetic call must not fabricate one.
+                const syntheticArgs = { requirement: parsed.requirement };
+                if (typeof parsed.duration === 'number') {
+                    syntheticArgs.duration = parsed.duration;
+                }
                 return {
                     id: `synthetic_query_requirement_${iterationCount}`,
                     type: 'function',
                     function: {
                         name: 'query_requirement',
-                        arguments: JSON.stringify({
-                            requirement: parsed.requirement,
-                            duration: parsed.duration,
-                        }),
+                        arguments: JSON.stringify(syntheticArgs),
                     },
                 };
             }
@@ -165,10 +168,10 @@ const functionSchemas = [
                     },
                     duration: {
                         type: 'number',
-                        description: 'Display duration per item in seconds',
+                        description: 'Display duration per item in seconds. Omit for auto timing: video/audio items then carry no duration and play their natural length (DP-1 §4.1); static items use the configured default.',
                     },
                 },
-                required: ['requirement', 'duration'],
+                required: ['requirement'],
             },
         },
     },
@@ -207,10 +210,10 @@ const functionSchemas = [
                     },
                     duration: {
                         type: 'number',
-                        description: 'Duration per item in seconds',
+                        description: "Duration per item in seconds. Omit to keep each feed item's own timing.",
                     },
                 },
-                required: ['playlistName', 'quantity', 'duration'],
+                required: ['playlistName', 'quantity'],
             },
         },
     },
@@ -474,6 +477,12 @@ function buildOrchestratorSystemPrompt(params) {
         }
     })
         .join('\n');
+    // Spell out the duration argument once: an explicit setting is passed
+    // through verbatim; otherwise the model must OMIT duration so item-build
+    // applies auto timing (video/audio natural length per DP-1 §4.1).
+    const durationArgText = typeof playlistSettings.durationPerItem === 'number'
+        ? `call query_requirement(requirement, duration=${playlistSettings.durationPerItem}).`
+        : 'call query_requirement(requirement) WITHOUT a duration argument (auto timing).';
     const hasDevice = playlistSettings.deviceName !== undefined;
     const sendStep = hasDevice
         ? `6) If verification passed → you MUST call send_to_device({ playlistId: <the_playlistId>, deviceName: "${playlistSettings.deviceName || 'first-device'}" }) before finishing.
@@ -488,7 +497,7 @@ REQUIREMENTS
 ${requirementsText}
 
 PLAYLIST SETTINGS
-- durationPerItem: ${playlistSettings.durationPerItem || 10}
+- durationPerItem: ${typeof playlistSettings.durationPerItem === 'number' ? playlistSettings.durationPerItem : 'auto (omit duration: video/audio play natural length, static media uses configured default)'}
 - title: ${playlistSettings.title || 'auto'}
 - slug: ${playlistSettings.slug || 'auto'}
 - preserveOrder: ${playlistSettings.preserveOrder !== false ? 'true' : 'false'}
@@ -517,14 +526,14 @@ KEY RULES
 
 DECISION LOOP
 1) For each requirement in order:
-   - build_playlist: call query_requirement(requirement, duration=${playlistSettings.durationPerItem || 10}).
+   - build_playlist: ${durationArgText}
      Returns array with minimal item data including id field. Collect the id values.
-   - feral_file_artwork: call query_requirement(requirement, duration=${playlistSettings.durationPerItem || 10}).
+   - feral_file_artwork: ${durationArgText}
      Returns array with minimal item data including id field. Collect the id values.
    - query_address:
      • if ownerAddress endsWith .eth/.tez → resolve_domains([domain]); if resolved → use returned address; if not → mark failed and continue.
-     • if ownerAddress is 0x…/tz… → call query_requirement(requirement, duration=${playlistSettings.durationPerItem || 10}).
-   - fetch_feed: search_feed_playlist(name) → take bestMatch → fetch_feed_playlist_items(bestMatch, quantity, duration=${playlistSettings.durationPerItem || 10}).
+     • if ownerAddress is 0x…/tz… → ${durationArgText}
+   - fetch_feed: search_feed_playlist(name) → take bestMatch → fetch_feed_playlist_items(bestMatch, quantity${typeof playlistSettings.durationPerItem === 'number' ? `, duration=${playlistSettings.durationPerItem}` : ''}).
    - Collect item IDs across all steps in an array (let's call it collectedItemIds).
 2) If zero items → explain briefly and finish.
 3) If some requirements failed and interactive mode → ask user; otherwise proceed with available items.

package/dist/src/commands/find.js

@@ -47,8 +47,10 @@ const marketplace_url_1 = require("../utilities/marketplace-url");
 const ff_marketplace_1 = require("../utilities/ff-marketplace");
 const objkt_marketplace_1 = require("../utilities/objkt-marketplace");
 const ab_marketplace_1 = require("../utilities/ab-marketplace");
+const opensea_marketplace_1 = require("../utilities/opensea-marketplace");
 const fxhash_marketplace_1 = require("../utilities/fxhash-marketplace");
 const neort_marketplace_1 = require("../utilities/neort-marketplace");
+const verse_marketplace_1 = require("../utilities/verse-marketplace");
 const raster_client_1 = require("../utilities/raster-client");
 const ff1_device_1 = require("../utilities/ff1-device");
 // nft-indexer + playlist-builder are still CommonJS; require keeps interop simple.
@@ -66,7 +68,7 @@ const DP1_MAX_ITEMS = 1024;
 const RASTER_PAGE_SIZE = 100;
 exports.findCommand = new commander_1.Command('find')
     .description('Find an artwork on the web and build a DP-1 playlist')
-    .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address')
+    .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort / Verse), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address')
     .option('-o, --output <path>', 'Save the playlist to this file (default: ./<slug>.json)')
     .option('-l, --limit <n>', 'Max tokens to include from the series (default: all)')
     .option('-p, --play', 'Play the playlist on an FF1 device after building')
@@ -81,7 +83,7 @@ exports.findCommand = new commander_1.Command('find')
         const parsed = (0, marketplace_url_1.parseFindInput)(input);
         if (!parsed) {
             console.error(chalk_1.default.red('Could not understand input.'));
-            console.error(chalk_1.default.dim('Supported URLs: Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort. ' +
+            console.error(chalk_1.default.dim('Supported URLs: Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort, Verse. ' +
                 'Or: `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, ' +
                 'or a wallet address (`0x...` / `tz1.../tz2.../tz3...`).'));
             process.exit(1);
@@ -128,7 +130,8 @@ exports.findCommand = new commander_1.Command('find')
         console.log(chalk_1.default.dim(`Indexing ${tokens.length} token${tokens.length === 1 ? '' : 's'} via FF indexer...`));
         // Second positional arg on getNFTTokenInfoBatch is `duration` (DP-1 item
         // display seconds), not concurrency — concurrency is hardcoded inside.
-        // Omit it so the default (10s) applies; no misleading constant on this side.
+        // Omit it for auto timing: video/audio items carry no duration and play
+        // their natural length (DP-1 §4.1); static items get the config default.
         const items = await getNFTTokenInfoBatch(tokens.map((t) => ({
             chain: t.chain,
             contractAddress: t.contract,
@@ -182,6 +185,10 @@ async function resolveTarget(parsed, skipPrompt) {
         const coords = await (0, ab_marketplace_1.resolveArtBlocksCollection)(parsed.slug);
         return resolveCoords(coords);
     }
+    if (parsed.kind === 'os-collection') {
+        const coords = await (0, opensea_marketplace_1.resolveOpenSeaCollection)(parsed.slug);
+        return resolveCoords(coords);
+    }
     if (parsed.kind === 'fxhash-iteration') {
         const coords = await (0, fxhash_marketplace_1.resolveFxhashIteration)(parsed.slug);
         return resolveCoords(coords);
@@ -190,6 +197,10 @@ async function resolveTarget(parsed, skipPrompt) {
         const coords = await (0, fxhash_marketplace_1.resolveFxhashProject)(parsed.slug);
         return resolveCoords(coords);
     }
+    if (parsed.kind === 'verse-series') {
+        const coords = await (0, verse_marketplace_1.resolveVerseSeries)(parsed.slug);
+        return resolveCoords(coords);
+    }
     if (parsed.kind === 'address') {
         const artistId = await (0, raster_client_1.resolveAddressToArtist)(parsed.address);
         if (artistId === null) {
@@ -482,7 +493,8 @@ async function runNeortFind(id, options) {
         console.log(chalk_1.default.dim('Cancelled.'));
         return;
     }
-    const item = buildUrlItem(art.assetUrl, 10, { title: art.title });
+    // No explicit duration: auto timing (video/audio play natural length).
+    const item = buildUrlItem(art.assetUrl, undefined, { title: art.title });
     const playlistTitle = `${artistLabel} — ${art.title}`;
     const playlist = await buildDP1Playlist({ items: [item], title: playlistTitle });
     const outputPath = options.output ?? `${playlist.slug || 'playlist'}.json`;

package/dist/src/commands/helpers/config-files.js

@@ -1,24 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isMissingConfigValue = isMissingConfigValue;
+exports.isMissingConfigValue = void 0;
 exports.readConfigFile = readConfigFile;
 exports.resolveExistingConfigPath = resolveExistingConfigPath;
 exports.ensureConfigFile = ensureConfigFile;
 const fs_1 = require("fs");
 const config_1 = require("../../config");
-// Treat any value containing the YOUR_/your_ placeholder pattern as missing,
-// since createSampleConfig writes those literal placeholders into new files
-// and we should not let the user proceed with an unfilled value.
-const placeholderPattern = /YOUR_|your_/;
-/**
- * Whether a config value is unset or still holds a sample placeholder.
- */
-function isMissingConfigValue(value) {
-    if (!value) {
-        return true;
-    }
-    return placeholderPattern.test(value);
-}
+var config_placeholders_1 = require("../../utilities/config-placeholders");
+Object.defineProperty(exports, "isMissingConfigValue", { enumerable: true, get: function () { return config_placeholders_1.isMissingConfigValue; } });
 /**
  * Read and parse a config.json file at the given path.
  */

package/dist/src/commands/play.js

@@ -55,7 +55,9 @@ exports.playCommand = new commander_1.Command('play')
     .action(async (source, options) => {
     try {
         const config = (0, config_1.getConfig)();
-        const resolved = await (0, playlist_source_1.resolvePlaySource)(source, config.defaultDuration || 10);
+        // No explicit duration: a direct video/audio URL plays its natural
+        // length (DP-1 §4.1); static media uses config.defaultDuration.
+        const resolved = await (0, playlist_source_1.resolvePlaySource)(source);
         const isPlaylistSource = resolved.kind === 'playlist';
         const sourceLabel = isPlaylistSource
             ? `${resolved.sourceType}: ${resolved.source}`

package/dist/src/commands/setup.js

@@ -14,6 +14,7 @@ const config_1 = require("../config");
 const config_files_1 = require("./helpers/config-files");
 const device_discovery_1 = require("./helpers/device-discovery");
 const prompt_1 = require("./helpers/prompt");
+const config_placeholders_1 = require("../utilities/config-placeholders");
 const playlist_signing_role_1 = require("../utilities/playlist-signing-role");
 exports.setupCommand = new commander_1.Command('setup')
     .description('Guided setup for config, signing key, and device')
@@ -139,7 +140,12 @@ exports.setupCommand = new commander_1.Command('setup')
                 role: signingRole,
             };
         }
-        const existingDevices = config.ff1Devices?.devices || [];
+        const configuredDevices = (0, config_placeholders_1.configuredFF1Devices)(config.ff1Devices?.devices || []);
+        const existingDevices = configuredDevices;
+        // Drop bundled example rows before discovery. Otherwise setup sees the
+        // sample placeholder as an existing device and lets users skip the device
+        // prompt without ever configuring a usable FF1 host.
+        config.ff1Devices = { devices: configuredDevices };
         if (existingDevices.length > 0) {
             console.log(chalk_1.default.dim(`\nConfigured devices: ${existingDevices.map((d) => d.name || d.host).join(', ')}`));
         }
@@ -198,7 +204,7 @@ exports.setupCommand = new commander_1.Command('setup')
         console.log(chalk_1.default.dim(`   Config: ${configPath}`));
         const hasApiKey = !(0, config_files_1.isMissingConfigValue)(config.models[selectedModel]?.apiKey);
         const hasSigningKey = !(0, config_files_1.isMissingConfigValue)(config.playlist?.privateKey || '');
-        const hasDevice = Boolean(config.ff1Devices?.devices?.[0]?.host);
+        const hasDevice = (0, config_placeholders_1.configuredFF1Devices)(config.ff1Devices?.devices || []).length > 0;
         if (!hasSigningKey || !hasDevice) {
             console.log(chalk_1.default.yellow('\nNext steps:'));
             if (!hasSigningKey) {

package/dist/src/commands/status.js

@@ -10,6 +10,7 @@ const config_files_1 = require("./helpers/config-files");
 const config_1 = require("../config");
 const ed25519_key_derive_1 = require("../utilities/ed25519-key-derive");
 const playlist_signing_role_1 = require("../utilities/playlist-signing-role");
+const config_placeholders_1 = require("../utilities/config-placeholders");
 exports.statusCommand = new commander_1.Command('status')
     .description('Show configuration status')
     .action(async () => {
@@ -32,6 +33,7 @@ exports.statusCommand = new commander_1.Command('status')
         const playlistKeyMaterial = playlistConfig.privateKey?.trim() || '';
         const playlistKeyError = playlistKeyMaterial.length > 0 ? validatePlaylistPrivateKey(playlistKeyMaterial) : null;
         const hasPlaylistSigningKey = playlistKeyMaterial.length > 0 && playlistKeyError === null;
+        const configuredDevices = (0, config_placeholders_1.configuredFF1Devices)(config.ff1Devices?.devices || []);
         let hasValidPlaylistRole = false;
         let playlistRoleDetail;
         let playlistRoleError;
@@ -75,12 +77,10 @@ exports.statusCommand = new commander_1.Command('status')
                 hint: ' (used when signing playlists)',
             },
             {
-                label: `FF1 devices (${config.ff1Devices?.devices?.length || 0})`,
-                ok: (config.ff1Devices?.devices?.length || 0) > 0 &&
-                    (config.ff1Devices?.devices || []).every((d) => !(0, config_files_1.isMissingConfigValue)(d.host)),
-                detail: (config.ff1Devices?.devices || [])
-                    .map((d) => `${d.name || 'unnamed'} → ${d.host}`)
-                    .join(', ') || undefined,
+                label: `FF1 devices (${configuredDevices.length})`,
+                ok: configuredDevices.length > 0,
+                detail: configuredDevices.map((d) => `${d.name || 'unnamed'} → ${d.host}`).join(', ') ||
+                    undefined,
             },
         ];
         console.log(chalk_1.default.blue('\n🔎 FF1 Status\n'));

package/dist/src/config.js

@@ -18,6 +18,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const playlist_signing_role_1 = require("./utilities/playlist-signing-role");
+const config_placeholders_1 = require("./utilities/config-placeholders");
 // One-shot legacy config migration: copy `$XDG_CONFIG_HOME/ff1/config.json` to
 // `$XDG_CONFIG_HOME/ff-cli/config.json` on first read after upgrading from
 // `ff1-cli`. The check is cheap (two fs.existsSync calls) and the
@@ -285,7 +286,7 @@ function getFF1DeviceConfig() {
     const config = getConfig();
     const ff1Devices = config.ff1Devices || { devices: [] };
     return {
-        devices: ff1Devices.devices || [],
+        devices: (0, config_placeholders_1.configuredFF1Devices)(ff1Devices.devices || []),
     };
 }
 /**
@@ -338,7 +339,7 @@ function validateConfig(modelName) {
             return { valid: false, errors };
         }
         const modelConfig = config.models[selectedModel];
-        if (!modelConfig.apiKey || modelConfig.apiKey === 'your_api_key_here') {
+        if ((0, config_placeholders_1.isMissingConfigValue)(modelConfig.apiKey)) {
             errors.push(`API key for "${selectedModel}" is missing or not configured`);
         }
         if (!modelConfig.baseURL) {

package/dist/src/intent-parser/index.js

@@ -164,7 +164,7 @@ EXAMPLES (fetch_feed)
 - "Pick 3 artworks from Social Codes and 2 from a2p. Mix them up." → \`fetch_feed\` { playlistName: "Social Codes", quantity: 3 } + \`fetch_feed\` { playlistName: "a2p", quantity: 2 }, and set \`playlistSettings.preserveOrder\` = false
 
 PLAYLIST SETTINGS EXTRACTION
-- durationPerItem: parse phrases (e.g., "6 seconds each" → 6)
+- durationPerItem: parse phrases (e.g., "6 seconds each" → 6); OMIT entirely when the user gives no per-item time — omitted means auto timing (video/audio play their natural length, static media uses the configured default). Never invent a number.
 - preserveOrder: default true; synonyms ("shuffle", "randomize", "mix", "mix them up", "scramble") → false
 - title/slug: optional; include only if provided by the user
 - deviceName: from phrases like "send to", "display on", "play on", "push to"${hasDevices ? '\n- available devices:\n' + deviceInfo.replace('\n\nAVAILABLE FF1 DEVICES:\n', '') : ''}
@@ -341,7 +341,7 @@ const intentParserFunctionSchemas = [
                             },
                             durationPerItem: {
                                 type: 'number',
-                                description: 'Duration per item in seconds (e.g., 5 for "5 seconds each")',
+                                description: 'Duration per item in seconds (e.g., 5 for "5 seconds each"). Omit when the user gives no per-item time: omitted = auto timing (video/audio play natural length per DP-1 §4.1).',
                             },
                             totalDuration: {
                                 type: 'number',

package/dist/src/intent-parser/utils.js

@@ -15,10 +15,12 @@ const chalk_1 = __importDefault(require("chalk"));
  * @param {Object} params - Parsed parameters
  * @param {Array<Object>} params.requirements - Array of requirements
  * @param {Object} [params.playlistSettings] - Playlist settings
- * @param {Object} config - Application config
+ * @param {Object} _config - Application config (kept in the signature for
+ *   call-site stability; no constraint reads it since durationPerItem
+ *   pre-filling was removed in favor of DP-1 §4.1 auto timing)
  * @returns {Object} Validated parameters
  */
-function applyConstraints(params, config) {
+function applyConstraints(params, _config) {
     // Validate requirements array
     if (!params.requirements || !Array.isArray(params.requirements)) {
         throw new Error('Requirements must be an array');
@@ -101,10 +103,11 @@ function applyConstraints(params, config) {
     if (!params.playlistSettings) {
         params.playlistSettings = {};
     }
-    // Only set durationPerItem if not already specified
-    if (params.playlistSettings.durationPerItem === undefined) {
-        params.playlistSettings.durationPerItem = config.defaultDuration || 10;
-    }
+    // durationPerItem stays undefined unless the user asked for a per-item
+    // time: absence means auto timing downstream (video/audio omit duration
+    // and play their natural length per DP-1 §4.1; static media falls back to
+    // config.defaultDuration at item-build time). Pre-filling a number here
+    // would force-cut every video item.
     // Only set preserveOrder if not already specified
     if (params.playlistSettings.preserveOrder === undefined) {
         params.playlistSettings.preserveOrder = true;

package/dist/src/main.js

@@ -228,11 +228,14 @@ function validateRequirements(requirements) {
  * @returns {Object} Settings with defaults
  */
 function applyPlaylistDefaults(settings = {}) {
-    const config = (0, config_1.getConfig)();
     return {
         title: settings.title || null,
         slug: settings.slug || null,
-        durationPerItem: settings.durationPerItem || config.defaultDuration || 10,
+        // Leave durationPerItem undefined when not requested: absence means auto
+        // timing downstream (video/audio omit duration and play their natural
+        // length per DP-1 §4.1; static media falls back to config.defaultDuration
+        // at item-build time). Filling a number here would force-cut video items.
+        durationPerItem: settings.durationPerItem,
         preserveOrder: settings.preserveOrder !== false,
         deviceName: settings.deviceName,
     };

package/dist/src/utilities/config-placeholders.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMissingConfigValue = isMissingConfigValue;
+exports.configuredFF1Devices = configuredFF1Devices;
+/**
+ * configPlaceholders identifies values copied from config.json.example.
+ *
+ * The sample file is useful for manual editing, but runtime flows must treat
+ * those literal placeholders as unset so setup cannot mistake example rows for
+ * configured devices.
+ */
+const CONFIG_PLACEHOLDER_PATTERN = /YOUR_|your_/;
+/**
+ * isMissingConfigValue reports whether a config string is empty or still a
+ * sample placeholder.
+ *
+ * @param {string | null | undefined} value - Config value to inspect.
+ * @returns {boolean} True when the value should be treated as unset.
+ */
+function isMissingConfigValue(value) {
+    if (!value) {
+        return true;
+    }
+    return CONFIG_PLACEHOLDER_PATTERN.test(value);
+}
+/**
+ * configuredFF1Devices returns only device rows with a real host.
+ *
+ * @param {T[]} devices - Device rows from config.json.
+ * @returns {T[]} Rows that can be used for FF1 network operations.
+ */
+function configuredFF1Devices(devices = []) {
+    return devices.filter((device) => !isMissingConfigValue(device.host));
+}

package/dist/src/utilities/feed-fetcher.js

@@ -333,7 +333,7 @@ function shuffleArray(array) {
  *
  * @param {Object} playlist - DP1 playlist object
  * @param {number} quantity - Number of items to extract
- * @param {number} duration - Duration per item in seconds
+ * @param {number} [duration] - Explicit display seconds; omit to keep item timing
  * @param {boolean} shuffle - Whether to shuffle and randomly select items
  * @returns {Array<Object>} Array of DP1 playlist items
  */
@@ -348,12 +348,19 @@ function extractPlaylistItems(playlist, quantity, duration, shuffle = true) {
     }
     // Take requested quantity
     items = items.slice(0, quantity);
-    // Override duration and ensure created field exists
-    items = items.map((item) => ({
-        ...item,
-        duration: duration || item.duration,
-        created: item.created || new Date().toISOString(), // Ensure created field exists
-    }));
+    // Apply an explicit duration override when one was requested; otherwise
+    // keep each item's own timing (including intentionally absent duration,
+    // which DP-1 §4.1 uses for natural-length playback of video/audio).
+    items = items.map((item) => {
+        const next = {
+            ...item,
+            created: item.created || new Date().toISOString(), // Ensure created field exists
+        };
+        if (typeof duration === 'number') {
+            next.duration = duration;
+        }
+        return next;
+    });
     return items;
 }
 /**
@@ -361,10 +368,10 @@ function extractPlaylistItems(playlist, quantity, duration, shuffle = true) {
  *
  * @param {string} playlistName - Exact playlist name
  * @param {number} quantity - Number of items to fetch
- * @param {number} duration - Duration per item
+ * @param {number} [duration] - Explicit display seconds; omit to keep item timing
  * @returns {Promise<Object>} Result with items
  */
-async function fetchFeedPlaylistDirect(playlistName, quantity = 5, duration = 10) {
+async function fetchFeedPlaylistDirect(playlistName, quantity = 5, duration) {
     const feedUrls = getFeedApiUrls();
     console.log(chalk.cyan(`Searching for playlist "${playlistName}" in ${feedUrls.length} source(s)...`));
     const result = await searchExactPlaylist(playlistName);
@@ -395,10 +402,10 @@ async function fetchFeedPlaylistDirect(playlistName, quantity = 5, duration = 10
  *
  * @param {string} playlistName - Playlist name (can be fuzzy)
  * @param {number} quantity - Number of items to fetch
- * @param {number} duration - Duration per item
+ * @param {number} [duration] - Explicit display seconds; omit to keep item timing
  * @returns {Promise<Object>} Result with best match and map for lookup
  */
-async function searchFeedPlaylists(playlistName, quantity = 5, duration = 10) {
+async function searchFeedPlaylists(playlistName, quantity = 5, duration) {
     const feedUrls = getFeedApiUrls();
     console.log(chalk.cyan(`Searching for playlist "${playlistName}" in ${feedUrls.length} source(s)...`));
     const result = await findBestMatchingPlaylist(playlistName);
@@ -429,12 +436,12 @@ async function searchFeedPlaylists(playlistName, quantity = 5, duration = 10) {
  *
  * @param {string} playlistIdOrName - Playlist ID, slug, or exact name
  * @param {number} quantity - Number of items to fetch
- * @param {number} duration - Duration per item
+ * @param {number} [duration] - Explicit display seconds; omit to keep item timing
  * @param {Object} playlistMap - Optional map of names to IDs for lookup
  * @param {boolean} shuffle - Whether to shuffle and randomly select items
  * @returns {Promise<Object>} Result with items
  */
-async function fetchPlaylistItems(playlistIdOrName, quantity = 5, duration = 10, playlistMap = null, shuffle = true) {
+async function fetchPlaylistItems(playlistIdOrName, quantity = 5, duration, playlistMap = null, shuffle = true) {
     try {
         let playlistId = playlistIdOrName;
         let feedUrl = null;

package/dist/src/utilities/index.js

@@ -95,10 +95,10 @@ function isLikelyEvmAddress(address) {
  *
  * @param {string} contractAddress - Contract address
  * @param {number|string} [quantity] - Number of random tokens to select
- * @param {number} duration - Duration per item in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
  * @returns {Promise<Array<Object>>} Array of DP1 items
  */
-async function queryTokensByContractAddress(contractAddress, quantity, duration = 10) {
+async function queryTokensByContractAddress(contractAddress, quantity, duration) {
     console.log(chalk.cyan(`   Fetching ${quantity || 100} random token(s) from contract ${contractAddress.substring(0, 10)}...`));
     const limit = Math.min(quantity || 100, 100);
     const result = await nftIndexer.queryTokensByContract(contractAddress, limit);
@@ -141,10 +141,10 @@ function initializeUtilities(_config) {
  *
  * @param {string} ownerAddress - Owner wallet address
  * @param {number|string} [quantity] - Number of random tokens to select, or "all" to fetch all tokens
- * @param {number} duration - Duration per item in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
  * @returns {Promise<Array>} Array of DP1 playlist items
  */
-async function queryTokensByAddress(ownerAddress, quantity, duration = 10, options = {}) {
+async function queryTokensByAddress(ownerAddress, quantity, duration, options = {}) {
     try {
         const { suppressNotFoundGuidance = false } = options;
         const shouldFetchAll = quantity === 'all' || quantity === undefined || quantity === null;
@@ -216,7 +216,7 @@ async function queryTokensByAddress(ownerAddress, quantity, duration = 10, optio
         if (typeof quantity === 'number' && selectedTokens.length > quantity) {
             selectedTokens = shuffleArray([...selectedTokens]).slice(0, quantity);
         }
-        const tokenCountKey = `${ownerAddress}|${quantity ?? 'all'}|${duration}`;
+        const tokenCountKey = `${ownerAddress}|${quantity ?? 'all'}|${duration ?? 'auto'}`;
         if (!printedTokenCountKeys.has(tokenCountKey)) {
             console.log(chalk.dim(`Got ${selectedTokens.length} token(s)`));
             printedTokenCountKeys.add(tokenCountKey);
@@ -243,10 +243,10 @@ async function queryTokensByAddress(ownerAddress, quantity, duration = 10, optio
  * @param {string} [requirement.ownerAddress] - Owner address (for query_address)
  * @param {string} [requirement.playlistName] - Feed playlist name (for fetch_feed)
  * @param {number} [requirement.quantity] - Number of items
- * @param {number} duration - Duration per item in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
  * @returns {Promise<Array>} Array of DP1 playlist items
  */
-async function queryRequirement(requirement, duration = 10) {
+async function queryRequirement(requirement, duration) {
     const { type, blockchain, contractAddress, tokenIds, ownerAddress, playlistName, quantity, artworkId, } = requirement;
     // Handle query_address type
     if (type === 'query_address') {
@@ -458,7 +458,9 @@ async function buildPlaylistDirect(params, options = {}) {
     const { requirements, playlistSettings } = params;
     const { verbose = false, outputPath = 'playlist.json' } = options;
     const allItems = [];
-    const duration = playlistSettings.durationPerItem || 10;
+    // Undefined means auto timing: video/audio items omit duration and play
+    // their natural length (DP-1 §4.1); static items get the configured default.
+    const duration = playlistSettings.durationPerItem;
     console.log(chalk.cyan('\nBuilding playlist from your requirements...\n'));
     // Process each requirement
     for (let i = 0; i < requirements.length; i++) {

package/dist/src/utilities/marketplace-url.js

@@ -3,7 +3,7 @@
  * Marketplace URL parser for `ff-cli find`.
  *
  * Accepts user input in any of these forms and returns a normalized result:
- *  - Marketplace token URL (Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort)
+ *  - Marketplace token URL (Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort, Verse)
  *  - Raw on-chain coordinates: "ethereum:0xabc...:123" / "tezos:KT1...:456"
  *  - Wallet address: 0x{40-hex} (Ethereum) or tz1/tz2/tz3{33} (Tezos)
  *
@@ -25,6 +25,7 @@ exports.parseFxhash = parseFxhash;
 exports.parseOpenSea = parseOpenSea;
 exports.parseSuperRare = parseSuperRare;
 exports.parseNeort = parseNeort;
+exports.parseVerse = parseVerse;
 exports.parseFeralFile = parseFeralFile;
 const ETH_ADDR = /^0x[a-fA-F0-9]{40}$/;
 const TEZOS_ADDR = /^(tz1|tz2|tz3)[1-9A-HJ-NP-Za-km-z]{33}$/;
@@ -97,6 +98,9 @@ function parseMarketplaceUrl(url) {
     if (host === 'neort.io' || host.endsWith('.neort.io')) {
         return parseNeort(url);
     }
+    if (host === 'verse.works' || host.endsWith('.verse.works')) {
+        return parseVerse(url);
+    }
     return null;
 }
 /**
@@ -242,7 +246,7 @@ function parseFxhash(url) {
  * OpenSea URL forms:
  *   opensea.io/assets/{chain}/{contract}/{tokenId}
  *   opensea.io/item/{chain}/{contract}/{tokenId}    — newer naming
- *   opensea.io/collection/{slug}                    — series slug (not yet)
+ *   opensea.io/collection/{slug}                    — collection slug (series)
  *
  * Only `ethereum` is in scope; other chains (matic, base, solana, etc.)
  * fall outside the FF indexer's coverage. Token URLs resolve end-to-end only
@@ -266,11 +270,15 @@ function parseOpenSea(url) {
             coords: { chain: 'ethereum', contract: tokenMatch[2].toLowerCase(), tokenId: tokenMatch[3] },
         };
     }
+    const collectionMatch = /^\/collection\/([a-z0-9][a-z0-9-]*)\/?$/.exec(url.pathname);
+    if (collectionMatch) {
+        return { kind: 'os-collection', slug: collectionMatch[1] };
+    }
     if (url.pathname.startsWith('/collection/')) {
         return {
             kind: 'unsupported',
-            reason: 'OpenSea `/collection/{slug}` URLs are not yet supported in v1. Paste a specific token ' +
-                'URL (opensea.io/assets/ethereum/{contract}/{tokenId}) or use `ethereum:{contract}:{tokenId}`.',
+            reason: `OpenSea collection URL not recognized: ${url.pathname}. ` +
+                'Expected opensea.io/collection/{slug} with no extra path segments.',
         };
     }
     return {
@@ -337,6 +345,43 @@ function parseNeort(url) {
         reason: `Neort URL not recognized: ${url.pathname}. Expected /art/{id}.`,
     };
 }
+/**
+ * Verse URL forms:
+ *   verse.works/items/ethereum/{contract}/{tokenId}  — direct Ethereum token
+ *   verse.works/series/{slug}                        — series page
+ *
+ * Verse item pages expose the on-chain coordinates directly in the path. Series
+ * pages do not include a JSON API in the public URL, but they render edition
+ * links with the same `/items/ethereum/...` shape; the async resolver fetches
+ * the series page and extracts a representative token for Raster enumeration.
+ */
+function parseVerse(url) {
+    let m = /^\/items\/ethereum\/(0x[a-fA-F0-9]{40})\/(\d+)\/?$/.exec(url.pathname);
+    if (m) {
+        return {
+            kind: 'token',
+            source: 'verse',
+            coords: { chain: 'ethereum', contract: m[1].toLowerCase(), tokenId: m[2] },
+        };
+    }
+    m = /^\/items\/([^/]+)\//.exec(url.pathname);
+    if (m) {
+        return {
+            kind: 'unsupported',
+            reason: `Verse ${m[1]} item URLs are not supported — ff-cli covers Ethereum and Tezos mainnet only. ` +
+                'Paste an Ethereum Verse item URL or raw `ethereum:{contract}:{tokenId}` coordinates.',
+        };
+    }
+    m = /^\/series\/([A-Za-z0-9][A-Za-z0-9_-]*)\/?$/.exec(url.pathname);
+    if (m) {
+        return { kind: 'verse-series', slug: m[1] };
+    }
+    return {
+        kind: 'unsupported',
+        reason: `Verse URL not recognized: ${url.pathname}. Expected ` +
+            '/items/ethereum/{contract}/{tokenId} or /series/{slug}.',
+    };
+}
 /**
  * Feral File URL forms (source of truth: feralfile-client app-routing
  * + collection-routing modules):

package/dist/src/utilities/nft-indexer.js

@@ -5,6 +5,7 @@
  */
 const GRAPHQL_ENDPOINT = 'https://indexer.feralfile.com/graphql';
 const logger = require('../logger');
+const { applyItemTiming } = require('./playlist-builder');
 // Polling configuration (in milliseconds)
 const POLLING_INTERVAL_MS = 2000; // Poll every 2 seconds
 const POLLING_TIMEOUT_MS = 60000; // Max poll for 1 minute
@@ -318,12 +319,14 @@ function mapIndexerDataToStandardFormat(indexerData, chain) {
     const artistName = extractArtistName(display.artists);
     const name = display.name || `Token #${indexerData.token_number}`;
     const description = display.description || '';
+    const standard = detectTokenStandard(chain, indexerData.contract_address);
     return {
         success: true,
         token: {
             chain,
             contractAddress: indexerData.contract_address,
             tokenId: indexerData.token_number,
+            standard,
             name,
             description,
             image: {
@@ -352,10 +355,11 @@ function mapIndexerDataToStandardFormat(indexerData, chain) {
  * animation_url > image.url, ensuring the best quality media is used.
  *
  * @param {Object} tokenData - Token data in standard format
- * @param {number} duration - Display duration in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
+ *   (video/audio play natural length per DP-1 §4.1)
  * @returns {Object} DP1 item with source URL from indexer
  */
-function convertToDP1Item(tokenData, duration = 10) {
+function convertToDP1Item(tokenData, duration) {
     const { token } = tokenData;
     if (!token) {
         return {
@@ -433,14 +437,13 @@ function convertToDP1Item(tokenData, duration = 10) {
     const dp1Item = {
         id: itemId,
         source: sourceUrl,
-        duration: duration,
         license: 'open',
         created: new Date().toISOString(),
         provenance: {
             type: 'onChain',
             contract: {
                 chain: chainMap[token.chain.toLowerCase()] || 'other',
-                standard: 'other',
+                standard: token.standard || detectTokenStandard(token.chain, token.contractAddress),
                 address: token.contractAddress,
                 tokenId: String(token.tokenId),
             },
@@ -450,6 +453,7 @@ function convertToDP1Item(tokenData, duration = 10) {
     if (token.name) {
         dp1Item.title = token.name;
     }
+    applyItemTiming(dp1Item, { mimeType: token.image?.mimeType, sourceUrl }, duration);
     logger.debug('[NFT Indexer] ✓ Converted to DP1:', {
         title: token.name,
         source: sourceUrl ? sourceUrl.substring(0, 60) + '...' : '(no source URL)',
@@ -462,11 +466,11 @@ function convertToDP1Item(tokenData, duration = 10) {
 /**
  * Get NFT token information from indexer and return as DP1 item (supports single or batch)
  * @param {Object|Array} params - Token parameters (single object or array)
- * @param {number} duration - Display duration in seconds (default: 10)
+ * @param {number} [params.duration] - Explicit display seconds; omit for auto timing
  * @returns {Promise<Object>} DP1 item(s)
  */
 async function getNFTTokenInfo(params) {
-    const duration = params.duration || 10;
+    const duration = params.duration;
     // Handle array input for batch processing
     if (Array.isArray(params.tokens)) {
         return await getNFTTokenInfoBatch(params.tokens, duration);
@@ -493,7 +497,7 @@ async function getNFTTokenInfo(params) {
  * @param {Object} [options.mediaPoll] - Passed to pollForMediaAssets
  * @returns {Promise<Object>} DP1 item with success/error status
  */
-async function getNFTTokenInfoSingle(params, duration = 10, options = {}) {
+async function getNFTTokenInfoSingle(params, duration, options = {}) {
     let chain = params.chain;
     const { contractAddress, tokenId } = params;
     // DEFENSIVE: Auto-detect and correct chain based on contract address format
@@ -594,7 +598,7 @@ async function getNFTTokenInfoSingle(params, duration = 10, options = {}) {
  * @param {number} duration - Display duration in seconds
  * @returns {Promise<Array>} Array of DP1 items
  */
-async function getNFTTokenInfoBatch(tokens, duration = 10) {
+async function getNFTTokenInfoBatch(tokens, duration) {
     logger.info(`[NFT Indexer] 📦 Starting batch processing for ${tokens.length} token(s)...`);
     logger.debug('[NFT Indexer] Batch tokens:', tokens);
     const results = [];

package/dist/src/utilities/opensea-marketplace.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * OpenSea marketplace resolver.
+ *
+ * OpenSea collection URLs (`opensea.io/collection/{slug}`) point to a series,
+ * not a token. OpenSea's REST API requires an API key, so this resolver reads
+ * the public collection page instead: the server-rendered HTML embeds the
+ * first page of collection items as relay-style JSON where each item carries
+ * `"chain":{"identifier":...},"contractAddress":"0x...","tokenId":"..."`
+ * adjacently. One extracted (contract, tokenId) pair is enough — the standard
+ * Raster reverse-lookup then enumerates the rest of the series like any other
+ * marketplace.
+ *
+ * Extraction invariants (what must not change):
+ * - Match only the adjacent `contractAddress` + `tokenId` pattern. The page
+ *   also embeds payment-token contracts (WETH etc.) in other JSON shapes that
+ *   never carry an adjacent tokenId, so adjacency is the noise filter.
+ * - The most frequent contract among matches wins (collection items dominate
+ *   any stray adjacency), and its lowest tokenId is the deterministic seed.
+ * - tokenIds are compared as BigInt: ERC-721 ids can exceed Number range.
+ *
+ * Trade-off: scraping page HTML is less stable than a documented API, but the
+ * alternative (requiring every user to provision an OpenSea API key) defeats
+ * the paste-a-URL UX. Errors below name the fallback (`/item/` token URL) so
+ * a layout change degrades to a one-step workaround, not a dead end.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOpenSeaCollection = resolveOpenSeaCollection;
+const logger = __importStar(require("../logger"));
+const user_agent_1 = require("./user-agent");
+/**
+ * One embedded collection item: chain identifier, contract, tokenId. The
+ * `[^{}]*` keeps the chain object match from swallowing unrelated JSON when
+ * OpenSea reorders fields inside `chain`.
+ */
+const ITEM_PATTERN = /"chain":\{"identifier":"([a-z0-9_-]+)"[^{}]*\},"contractAddress":"(0x[a-fA-F0-9]{40})","tokenId":"(\d+)"/g;
+const FALLBACK_HINT = 'Paste a specific token URL (opensea.io/item/ethereum/{contract}/{tokenId}) ' +
+    'or use `ethereum:{contract}:{tokenId}`.';
+/**
+ * Resolve an OpenSea collection slug to its contract address + the lowest
+ * tokenId visible on the collection page (a representative seed for the
+ * Raster series lookup).
+ *
+ * @throws When the page cannot be fetched, embeds no recognizable items
+ *   (layout change or empty collection), or the collection is not on
+ *   Ethereum mainnet (outside FF indexer coverage).
+ */
+async function resolveOpenSeaCollection(slug) {
+    logger.debug(`[OpenSea] Resolving collection slug "${slug}"`);
+    const response = await fetch(`https://opensea.io/collection/${encodeURIComponent(slug)}`, {
+        headers: { 'User-Agent': user_agent_1.USER_AGENT, Accept: 'text/html' },
+    });
+    if (!response.ok) {
+        throw new Error(`OpenSea collection page returned ${response.status} ${response.statusText}. ` + FALLBACK_HINT);
+    }
+    const html = await response.text();
+    // Tally (contract → tokenIds) per chain so the dominant-contract rule and
+    // the ethereum-only guard can both give precise errors.
+    const byContract = new Map();
+    for (const match of html.matchAll(ITEM_PATTERN)) {
+        const [, chain, contract, tokenId] = match;
+        const key = contract.toLowerCase();
+        const entry = byContract.get(key) ?? { chain, tokenIds: [] };
+        entry.tokenIds.push(BigInt(tokenId));
+        byContract.set(key, entry);
+    }
+    if (byContract.size === 0) {
+        throw new Error(`OpenSea: no items found on the collection page for "${slug}". ` +
+            'The collection may be empty, or the page layout changed. ' +
+            FALLBACK_HINT);
+    }
+    let best = null;
+    for (const [contract, entry] of byContract) {
+        if (!best || entry.tokenIds.length > best.tokenIds.length) {
+            best = { contract, ...entry };
+        }
+    }
+    // byContract.size > 0 guarantees best is set; the check keeps TS honest.
+    if (!best) {
+        throw new Error(`OpenSea: no items found for "${slug}". ${FALLBACK_HINT}`);
+    }
+    if (best.chain !== 'ethereum') {
+        throw new Error(`OpenSea collection "${slug}" is on ${best.chain} — ff-cli covers Ethereum and ` +
+            'Tezos mainnet only. Paste an Ethereum-chain source instead.');
+    }
+    const seed = best.tokenIds.reduce((min, id) => (id < min ? id : min));
+    logger.debug(`[OpenSea] Resolved "${slug}" → ${best.contract} (seed tokenId ${seed}, ` +
+        `${best.tokenIds.length} items sampled)`);
+    return { chain: 'ethereum', contract: best.contract, tokenId: seed.toString() };
+}

package/dist/src/utilities/playlist-builder.js

@@ -2,8 +2,72 @@
  * Playlist Builder Utilities
  * Core functions for building and validating DP1 playlists
  */
-const { getPlaylistConfig } = require('../config');
+const { getPlaylistConfig, getConfig } = require('../config');
 const { signPlaylist } = require('./playlist-signer');
+/**
+ * isTimeBasedMedia reports whether an item's media has an intrinsic runtime
+ * (video or audio) per DP-1 §4.1 "time-based sources".
+ *
+ * Two signals are consulted because neither is reliable alone: indexer
+ * `display.mime_type` is authoritative when present but is defaulted to
+ * 'image/png' upstream when missing, and URL extensions only cover direct
+ * media links. Either signal saying video/audio wins.
+ *
+ * @param {string} [mimeType] - MIME type reported by the indexer, if any
+ * @param {string} [sourceUrl] - Item source URL, used as an extension fallback
+ * @returns {boolean} True when the media is video or audio
+ */
+function isTimeBasedMedia(mimeType, sourceUrl) {
+    const candidates = [String(mimeType || '').toLowerCase(), detectMimeType(sourceUrl)];
+    return candidates.some((mime) => mime.startsWith('video/') || mime.startsWith('audio/'));
+}
+/**
+ * applyItemTiming sets a DP1 item's playback timing per DP-1 §4.1.
+ *
+ * Invariant this function owns: an explicit numeric `duration` always wins
+ * and is stamped as-is. When `duration` is undefined/null ("auto"), a
+ * time-based source (video/audio) gets NO duration and `display.loop: false`,
+ * so a conformant player MUST advance at end-of-stream — the media plays its
+ * natural length. Static and code-based sources fall back to the configured
+ * `defaultDuration` because they have no intrinsic runtime to play out.
+ *
+ * Do not re-introduce an unconditional duration here: stamping a default on
+ * video items silently truncates or pads them (the bug this fixed).
+ *
+ * @param {Object} item - DP1 playlist item (mutated in place)
+ * @param {Object} mediaHints - Media signals for the time-based check
+ * @param {string} [mediaHints.mimeType] - Indexer-reported MIME type
+ * @param {string} [mediaHints.sourceUrl] - Item source URL
+ * @param {number} [duration] - Explicit display seconds; omit for auto
+ * @returns {Object} The same item, for chaining
+ */
+function applyItemTiming(item, mediaHints = {}, duration) {
+    if (typeof duration === 'number') {
+        item.duration = duration;
+        return item;
+    }
+    if (isTimeBasedMedia(mediaHints.mimeType, mediaHints.sourceUrl)) {
+        item.display = { ...(item.display || {}), loop: false };
+        return item;
+    }
+    item.duration = getDefaultStaticDuration();
+    return item;
+}
+/**
+ * getDefaultStaticDuration returns the configured per-item display seconds
+ * for media without an intrinsic runtime. Falls back to 10 when config is
+ * unavailable (e.g. unit tests without a config file).
+ *
+ * @returns {number} Display duration in seconds
+ */
+function getDefaultStaticDuration() {
+    try {
+        return getConfig().defaultDuration || 10;
+    }
+    catch (_error) {
+        return 10;
+    }
+}
 /**
  * Convert a string to a URL-friendly slug
  *
@@ -31,14 +95,16 @@ function slugify(value) {
  * Convert single NFT token info to DP1 playlist item
  *
  * @param {Object} tokenInfo - Token information from NFT indexer
- * @param {number} duration - Display duration in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
+ *   (video/audio play natural length per DP-1 §4.1, static media uses the
+ *   configured default — see applyItemTiming)
  * @returns {Object} DP1 playlist item
  * @throws {Error} When token data is missing or source is a data URI
  * @example
  * const item = convertTokenToDP1ItemSingle(tokenInfo, 10);
  * // Returns: { title, source, duration, license, provenance, ... }
  */
-function convertTokenToDP1ItemSingle(tokenInfo, duration = 10) {
+function convertTokenToDP1ItemSingle(tokenInfo, duration) {
     const { token } = tokenInfo;
     if (!token) {
         throw new Error('Invalid token info: missing token data');
@@ -75,7 +141,6 @@ function convertTokenToDP1ItemSingle(tokenInfo, duration = 10) {
         id: itemId,
         title: token.name || `Token #${token.tokenId}`,
         source: sourceUrl,
-        duration: duration,
         license: 'token', // NFTs are token-gated by default
         created: new Date().toISOString(),
         provenance: {
@@ -102,7 +167,7 @@ function convertTokenToDP1ItemSingle(tokenInfo, duration = 10) {
     if ((token.animation_url || token.animationUrl) && (token.image?.url || token.image)) {
         dp1Item.ref = token.image?.url || token.image;
     }
-    return dp1Item;
+    return applyItemTiming(dp1Item, { mimeType: token.image?.mimeType, sourceUrl }, duration);
 }
 /**
  * Convert NFT token info(s) to DP1 playlist item(s)
@@ -111,7 +176,7 @@ function convertTokenToDP1ItemSingle(tokenInfo, duration = 10) {
  * For collections, returns a map of token key to DP1 item.
  *
  * @param {Object|Array} tokenInfo - Token information (single object or map of tokens)
- * @param {number} duration - Display duration in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
  * @returns {Object} Map of token key to DP1 playlist item, or single item
  * @example
  * // Single token
@@ -120,7 +185,7 @@ function convertTokenToDP1ItemSingle(tokenInfo, duration = 10) {
  * // Multiple tokens
  * const items = convertTokenToDP1Item({ token1: info1, token2: info2 }, 10);
  */
-function convertTokenToDP1Item(tokenInfo, duration = 10) {
+function convertTokenToDP1Item(tokenInfo, duration) {
     // Handle array or map of tokens
     if (typeof tokenInfo === 'object' && !tokenInfo.token) {
         const results = {};
@@ -163,12 +228,12 @@ function convertTokenToDP1Item(tokenInfo, duration = 10) {
  * Excludes items with data URIs in their source field.
  *
  * @param {Array} tokensInfo - Array of token information
- * @param {number} duration - Display duration in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
  * @returns {Array} Array of DP1 playlist items
  * @example
  * const items = convertTokensToDP1Items(tokensInfoArray, 10);
  */
-function convertTokensToDP1Items(tokensInfo, duration = 10) {
+function convertTokensToDP1Items(tokensInfo, duration) {
     return tokensInfo
         .filter((info) => info.success && info.token)
         .map((info) => {
@@ -313,7 +378,10 @@ async function buildDP1Playlist(paramsOrItems, options = {}) {
                 margin: 0,
             },
             license: 'token',
-            duration: 10,
+            // No defaults.duration: items that should be timed carry an explicit
+            // duration already, and a playlist-level default would make conformant
+            // players time-cut items that intentionally omit duration to play
+            // their natural length (DP-1 §4.1 end-of-stream advance).
         },
     };
     // Always include slug (auto-generated when missing)
@@ -384,11 +452,14 @@ function validateDP1Playlist(playlist) {
             else if (typeof item.source !== 'string') {
                 errors.push(`Item ${index}: Field "source" must be a string (URI)`);
             }
-            if (item.duration === undefined || item.duration === null) {
-                errors.push(`Item ${index}: Missing required field "duration"`);
-            }
-            else if (typeof item.duration !== 'number' || item.duration < 1) {
-                errors.push(`Item ${index}: Field "duration" must be a number >= 1`);
+            // Duration is OPTIONAL per the DP-1 v1.1.0 schema (PlaylistItem requires
+            // only `source`; duration has `minimum: 0`). Absent duration is meaningful:
+            // time-based sources advance at end-of-stream (§4.1). Do not tighten this
+            // back to required — it would reject spec-valid playlists.
+            if (item.duration !== undefined && item.duration !== null) {
+                if (typeof item.duration !== 'number' || item.duration < 0) {
+                    errors.push(`Item ${index}: Field "duration" must be a number >= 0`);
+                }
             }
             if (!item.license) {
                 errors.push(`Item ${index}: Missing required field "license"`);
@@ -461,12 +532,13 @@ function detectMimeType(url) {
  * Build a single DP1 playlist item from a URL
  *
  * @param {string} url - Media URL
- * @param {number} duration - Duration per item in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
+ *   (video/audio URLs play their natural length per DP-1 §4.1)
  * @param {Object} [options] - Optional configuration
  * @param {string} [options.title] - Optional item title override
  * @returns {Object} DP1 playlist item
  */
-function buildUrlItem(url, duration = 10, options = {}) {
+function buildUrlItem(url, duration, options = {}) {
     const sourceUrl = String(url || '').trim();
     if (!sourceUrl) {
         throw new Error('URL is required to build a playlist item');
@@ -496,7 +568,6 @@ function buildUrlItem(url, duration = 10, options = {}) {
         id: itemId,
         title,
         source: sourceUrl,
-        duration: duration,
         license: 'open',
         created: new Date().toISOString(),
         provenance: {
@@ -509,7 +580,7 @@ function buildUrlItem(url, duration = 10, options = {}) {
             margin: 0,
         },
     };
-    return item;
+    return applyItemTiming(item, { sourceUrl }, duration);
 }
 module.exports = {
     convertTokenToDP1Item,
@@ -519,5 +590,7 @@ module.exports = {
     buildDP1Playlist,
     validateDP1Playlist,
     detectMimeType,
+    isTimeBasedMedia,
+    applyItemTiming,
     buildUrlItem,
 };

package/dist/src/utilities/playlist-source.js

@@ -93,7 +93,9 @@ async function loadPlaylistSource(source) {
  * `loadedAsPlaylist` boolean dance.
  *
  * @param source - User-supplied path or URL
- * @param defaultDuration - Duration (seconds) for the synthesized media item
+ * @param defaultDuration - Explicit duration (seconds) for the synthesized
+ *   media item; omit for auto timing (video/audio URLs play their natural
+ *   length per DP-1 §4.1, static media uses the configured default)
  * @returns Resolved playlist + metadata describing how it was loaded
  * @throws Error When `source` is empty, or is a non-URL file path that cannot be loaded
  */

package/dist/src/utilities/verse-marketplace.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVerseSeries = resolveVerseSeries;
+/**
+ * Resolve a Verse series slug to representative Ethereum token coordinates.
+ *
+ * Verse series pages render edition links as
+ * `/items/ethereum/{contract}/{tokenId}`. Using the first rendered edition
+ * keeps the resolver independent of private frontend state while still handing
+ * Raster a token it can use to enumerate the full series.
+ *
+ * @param slug - Verse series slug from `/series/{slug}`
+ * @returns Representative Ethereum token coordinates
+ * @throws Error when the page cannot be fetched or no Ethereum edition link is present
+ */
+async function resolveVerseSeries(slug) {
+    const url = `https://verse.works/series/${encodeURIComponent(slug)}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Verse series lookup failed for ${slug}: ${response.status}`);
+    }
+    const html = await response.text();
+    const match = /\/items\/ethereum\/(0x[a-fA-F0-9]{40})\/(\d+)/.exec(html);
+    if (!match) {
+        throw new Error(`Verse series ${slug} did not expose an Ethereum edition link. ` +
+            'Paste a specific Verse item URL or raw `ethereum:{contract}:{tokenId}` coordinates.');
+    }
+    return {
+        chain: 'ethereum',
+        contract: match[1].toLowerCase(),
+        tokenId: match[2],
+    };
+}

package/docs/CONFIGURATION.md

@@ -26,7 +26,8 @@ npm run dev -- config show
   - Used by orchestration to pick API, timeouts, and model identifier.
 
 - **defaultDuration** (number, seconds)
-  - Intended default per‑item display duration. Some flows pass an explicit duration; when omitted, utilities fall back to 10s.
+  - Default per‑item display duration for media without an intrinsic runtime (images, code-based works). Falls back to 10s when unset.
+  - Does NOT apply to video/audio items: with no explicit duration those are emitted without `duration` and with `display.loop: false`, so a DP-1 player advances at end-of-stream (§4.1) — the media plays its natural length.
 
 ## models
 

package/docs/FUNCTION_CALLING.md

@@ -75,12 +75,14 @@ Two options are available:
       "quantity": 2
     }
   ],
-  "playlistSettings": { "durationPerItem": 10, "preserveOrder": true, "title": "My Mix" }
+  "playlistSettings": { "preserveOrder": true, "title": "My Mix" }
 }
 ```
 
 This path bypasses the intent parser/orchestrator and calls utilities directly. Validation and sensible defaults are applied in `src/main.ts`.
 
+`playlistSettings.durationPerItem` is optional. Omit it for auto timing: video/audio items are emitted without `duration` and with `display.loop: false`, so a DP-1 player advances at end-of-stream (§4.1) and the media plays its natural length; static items fall back to `defaultDuration`. Set `durationPerItem` only to force a fixed display time on every item.
+
 2. AI‑orchestrated deterministic build (recommended for prompts): Use `chat` with `--verbose` to see tool calls. The orchestrator enforces complete requirement objects, then runs `verify_playlist` (structure only) before sending.
 
 ## Extending Functionality (OSS‑first)

package/docs/README.md

@@ -18,7 +18,7 @@ npm i -g @feralfile/cli
 curl -fsSL https://feralfile.com/ff-cli-install | bash
 ```
 
-Installs a prebuilt binary for macOS/Linux (no Node.js required).
+Installs a prebuilt bundle for macOS/Linux. Node.js 22 or newer must still be available in `PATH`; the bundle avoids a global npm install, not the Node runtime requirement.
 
 ## Configure
 
@@ -146,6 +146,11 @@ Notes:
   - Options: `-k, --key <privateKey>`, `-r, --role <role>`, `-o, --output <file>`
 - `play <source>` – Play a playlist file, playlist URL, or media URL on an FF1 device (runs `verify` before sending; only the CLI-synthesized media URL fallback is auto-signed when a signing key is configured; use `--skip-verify` to bypass the gate)
   - Options: `-d, --device <name>`, `--skip-verify` (skip signature verification; not recommended)
+- `find <input>` – Resolve a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist
+  - Sources: Art Blocks, Objkt, fxhash, OpenSea, SuperRare, Feral File, Neort, Verse, raw on-chain coordinates, and wallet addresses
+  - OpenSea forms: `/assets/ethereum/{contract}/{tokenId}`, `/item/ethereum/{contract}/{tokenId}`, and `/collection/{slug}` (Ethereum collections; the slug is resolved from the public collection page, no API key needed)
+  - Verse forms: `/items/ethereum/{contract}/{tokenId}` and `/series/{slug}`
+  - Options: `-o, --output <path>`, `-l, --limit <n>`, `-p, --play`, `-d, --device <name>`, `--publish`, `-s, --server <index>`, `-y, --yes`, `--skip-verify`
 - `publish <file>` – Publish a playlist to a feed server (runs `verify` before upload and rejects unsigned or broken playlists)
   - Options: `-s, --server <index>` (server index if multiple configured)
 - `ssh <enable|disable>` – Manage SSH access on an FF1 device
@@ -339,7 +344,7 @@ Setup preserves existing devices when adding new ones. See selection rules and e
 
 - Max 20 items total across all requirements
 - Per-source caps enforced in utilities
-- Duration per item defaults to 10s (configurable)
+- Per-item timing: when no duration is given, video/audio items carry **no** `duration` and `display.loop: false`, so the player advances at end-of-stream (DP-1 §4.1) — the media plays its natural length. Static items use `defaultDuration` (10s unless configured). An explicit duration always wins.
 
 ## Links
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)",
   "repository": {
     "type": "git",