@feralfile/cli 1.3.1 → 1.4.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "1.3.1",
+    "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,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");
@@ -129,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,
@@ -183,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);
@@ -487,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/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 = [];

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/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

@@ -148,6 +148,7 @@ Notes:
   - 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)
@@ -343,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.1",
+  "version": "1.4.0",
   "description": "CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)",
   "repository": {
     "type": "git",