@feralfile/cli 1.3.1 → 1.5.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "1.3.1",
+    "version": "1.5.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,6 +47,7 @@ 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");
@@ -108,28 +109,45 @@ exports.findCommand = new commander_1.Command('find')
         }
         console.log();
         const userLimit = parseLimitOption(options.limit);
-        const seriesTotal = target.kind === 'series' ? target.summary.tokenCount : 1;
         // Implicit cap: no --limit + series > 1024 → cap to DP-1 max with a
         // clear warning. Explicit `--limit > 1024` was already rejected by
         // parseLimitOption, so reaching here means either capped-by-default or
         // the user picked a value within spec.
         const limit = Math.min(userLimit, DP1_MAX_ITEMS);
-        if (userLimit === Number.POSITIVE_INFINITY && seriesTotal > DP1_MAX_ITEMS) {
-            console.log(chalk_1.default.yellow(`Series has ${seriesTotal} tokens; DP-1 caps playlists at ${DP1_MAX_ITEMS}. ` +
+        // Raster's GraphQL API exposes no series token counts, so enumerate
+        // tokens first (up to the effective limit) and confirm with the real
+        // number afterward. `hasMore` means the series continues past `limit`.
+        let tokens;
+        let seriesHasMore = false;
+        if (target.kind === 'series') {
+            const fetched = await fetchTokens(target.summary, limit);
+            tokens = fetched.tokens;
+            seriesHasMore = fetched.hasMore;
+        }
+        else {
+            tokens = [target.coords];
+        }
+        if (tokens.length === 0) {
+            console.error(chalk_1.default.red('Series has no tokens on supported chains (Ethereum + Tezos mainnet).'));
+            process.exit(1);
+        }
+        if (userLimit === Number.POSITIVE_INFINITY && seriesHasMore) {
+            console.log(chalk_1.default.yellow(`Series has more than ${DP1_MAX_ITEMS} tokens; DP-1 caps playlists at ${DP1_MAX_ITEMS}. ` +
                 `Building with the first ${DP1_MAX_ITEMS} — pass \`--limit N\` (≤ ${DP1_MAX_ITEMS}) for fewer.`));
             console.log();
         }
-        const willInclude = Math.min(seriesTotal, limit);
-        const shouldBuild = !!options.yes || !!options.output || (await confirmMakePlaylist(willInclude, seriesTotal));
+        const shouldBuild = !!options.yes ||
+            !!options.output ||
+            (await confirmMakePlaylist(tokens.length, seriesHasMore));
         if (!shouldBuild) {
             console.log(chalk_1.default.dim('Cancelled.'));
             return;
         }
-        const tokens = target.kind === 'series' ? await fetchTokens(target.summary, limit) : [target.coords];
         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,
@@ -183,6 +201,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);
@@ -196,32 +218,33 @@ async function resolveTarget(parsed, skipPrompt) {
         return resolveCoords(coords);
     }
     if (parsed.kind === 'address') {
-        const artistId = await (0, raster_client_1.resolveAddressToArtist)(parsed.address);
-        if (artistId === null) {
+        const artist = await (0, raster_client_1.resolveAddressToArtist)(parsed.address);
+        if (artist === null) {
             throw new Error(`No artist found on Raster for address ${parsed.address}. ` +
                 'Raster indexes artists by their on-chain addresses; this address may not yet be claimed.');
         }
-        const catalog = await (0, raster_client_1.listArtistArtworks)(artistId);
+        const catalog = await (0, raster_client_1.listArtistArtworks)(artist.id);
         if (catalog.length === 0) {
             throw new Error('Artist has no artworks indexed on Raster.');
         }
         const picked = await pickFromCatalog(catalog, skipPrompt);
-        const summary = await (0, raster_client_1.getArtworkSummary)(picked.artworkId);
-        return { kind: 'series', summary };
+        return {
+            kind: 'series',
+            summary: { artworkId: picked.artworkId, title: picked.title, artists: [artist] },
+        };
     }
     // `unsupported` is handled upstream; this branch keeps the type narrowing honest.
     throw new Error(`Unsupported parse result: ${parsed.kind}`);
 }
 /**
- * Resolve on-chain coords to a target. If Raster doesn't index this token
- * (404), fall back to single-token mode so we still build something playable.
+ * Resolve on-chain coords to a target. If Raster doesn't index this token,
+ * fall back to single-token mode so we still build something playable.
  */
 async function resolveCoords(coords) {
-    const lookup = await (0, raster_client_1.resolveTokenToArtwork)(coords.chain, coords.contract, coords.tokenId);
-    if (lookup === null) {
+    const summary = await (0, raster_client_1.resolveTokenToArtwork)(coords.chain, coords.contract, coords.tokenId);
+    if (summary === null) {
         return { kind: 'single', coords };
     }
-    const summary = await (0, raster_client_1.getArtworkSummary)(lookup.artworkId);
     return { kind: 'series', summary };
 }
 /**
@@ -252,11 +275,17 @@ function parseLimitOption(limitStr) {
     }
     return n;
 }
+/**
+ * Enumerate series tokens from Raster up to `limit`. `hasMore` reports
+ * whether the series continues past what was collected — the API exposes
+ * no total counts, so this is all the size information the flow gets.
+ */
 async function fetchTokens(summary, limit) {
     const collected = [];
     let cursor;
     let skipped = 0;
-    while (collected.length < limit) {
+    let hasMore = false;
+    for (;;) {
         const page = await (0, raster_client_1.listArtworkTokens)(summary.artworkId, {
             cursor,
             pageSize: RASTER_PAGE_SIZE,
@@ -264,6 +293,7 @@ async function fetchTokens(summary, limit) {
         skipped += page.skippedUnsupported;
         for (const t of page.tokens) {
             if (collected.length >= limit) {
+                hasMore = true;
                 break;
             }
             collected.push({
@@ -272,7 +302,11 @@ async function fetchTokens(summary, limit) {
                 tokenId: t.tokenId,
             });
         }
-        if (page.nextCursor === null) {
+        if (hasMore || page.nextCursor === null) {
+            break;
+        }
+        if (collected.length >= limit) {
+            hasMore = true;
             break;
         }
         cursor = page.nextCursor;
@@ -280,7 +314,7 @@ async function fetchTokens(summary, limit) {
     if (skipped > 0) {
         console.log(chalk_1.default.yellow(`  Skipped ${skipped} token${skipped === 1 ? '' : 's'} on unsupported chains (FF indexer covers eth + tezos mainnet only).`));
     }
-    return collected;
+    return { tokens: collected, hasMore };
 }
 async function pickFromCatalog(catalog, skipPrompt) {
     if (catalog.length === 1 || skipPrompt) {
@@ -288,8 +322,7 @@ async function pickFromCatalog(catalog, skipPrompt) {
     }
     console.log(chalk_1.default.cyan(`Found ${catalog.length} artworks for this artist:`));
     catalog.forEach((row, i) => {
-        const count = `${row.tokenCount} token${row.tokenCount === 1 ? '' : 's'}`;
-        console.log(chalk_1.default.dim(`  ${i}: ${row.title} (${count})`));
+        console.log(chalk_1.default.dim(`  ${i}: ${row.title}`));
     });
     console.log();
     const prompt = (0, prompt_1.createPrompt)();
@@ -304,9 +337,9 @@ async function pickFromCatalog(catalog, skipPrompt) {
     }
     return catalog[index];
 }
-async function confirmMakePlaylist(count, total) {
-    const noun = total === 1 ? 'token' : 'tokens';
-    const label = count < total ? `${count} of ${total} ${noun}` : `${count} ${noun}`;
+async function confirmMakePlaylist(count, hasMore) {
+    const noun = count === 1 ? 'token' : 'tokens';
+    const label = hasMore ? `the first ${count} ${noun}` : `${count} ${noun}`;
     const prompt = (0, prompt_1.createPrompt)();
     const yes = await (0, prompt_1.promptYesNo)(prompt.ask, `Build playlist with ${label}?`, true);
     prompt.close();
@@ -482,12 +515,13 @@ async function runNeortFind(id, options) {
     console.log(chalk_1.default.cyan(`Neort — ${artistLabel} — ${art.title}`));
     console.log(chalk_1.default.dim('  (Off-chain platform; building a one-item playlist directly from Neort.)'));
     console.log();
-    const shouldBuild = !!options.yes || !!options.output || (await confirmMakePlaylist(1, 1));
+    const shouldBuild = !!options.yes || !!options.output || (await confirmMakePlaylist(1, false));
     if (!shouldBuild) {
         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/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/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/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

@@ -246,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
@@ -270,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 {

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
@@ -354,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 {
@@ -435,7 +437,6 @@ function convertToDP1Item(tokenData, duration = 10) {
     const dp1Item = {
         id: itemId,
         source: sourceUrl,
-        duration: duration,
         license: 'open',
         created: new Date().toISOString(),
         provenance: {
@@ -452,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)',
@@ -464,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);
@@ -495,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
@@ -596,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 = [];