@softure-ai/marketing-kit 0.13.2 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/CHANGELOG.md +65 -0
  2. package/README.md +45 -13
  3. package/dist/config/schema.d.ts +2 -0
  4. package/dist/config/schema.d.ts.map +1 -1
  5. package/dist/config/schema.js +10 -2
  6. package/dist/config/schema.js.map +1 -1
  7. package/dist/footage/compose.d.ts +13 -0
  8. package/dist/footage/compose.d.ts.map +1 -1
  9. package/dist/footage/compose.js +26 -14
  10. package/dist/footage/compose.js.map +1 -1
  11. package/dist/footage/draft.js +2 -2
  12. package/dist/footage/draft.js.map +1 -1
  13. package/dist/footage/failure.d.ts +42 -0
  14. package/dist/footage/failure.d.ts.map +1 -0
  15. package/dist/footage/failure.js +14 -0
  16. package/dist/footage/failure.js.map +1 -0
  17. package/dist/footage/film-mix.d.ts +31 -0
  18. package/dist/footage/film-mix.d.ts.map +1 -0
  19. package/dist/footage/film-mix.js +45 -0
  20. package/dist/footage/film-mix.js.map +1 -0
  21. package/dist/footage/isolate-ranges.d.ts +47 -4
  22. package/dist/footage/isolate-ranges.d.ts.map +1 -1
  23. package/dist/footage/isolate-ranges.js +64 -14
  24. package/dist/footage/isolate-ranges.js.map +1 -1
  25. package/dist/footage/loudness.d.ts +91 -27
  26. package/dist/footage/loudness.d.ts.map +1 -1
  27. package/dist/footage/loudness.js +143 -69
  28. package/dist/footage/loudness.js.map +1 -1
  29. package/dist/footage/paid.d.ts +3 -0
  30. package/dist/footage/paid.d.ts.map +1 -1
  31. package/dist/footage/paid.js +2 -1
  32. package/dist/footage/paid.js.map +1 -1
  33. package/dist/footage/pipeline.d.ts +40 -12
  34. package/dist/footage/pipeline.d.ts.map +1 -1
  35. package/dist/footage/pipeline.js +137 -80
  36. package/dist/footage/pipeline.js.map +1 -1
  37. package/dist/footage/publish.js +4 -4
  38. package/dist/footage/publish.js.map +1 -1
  39. package/dist/footage/speech-ranges.d.ts +29 -4
  40. package/dist/footage/speech-ranges.d.ts.map +1 -1
  41. package/dist/footage/speech-ranges.js +56 -11
  42. package/dist/footage/speech-ranges.js.map +1 -1
  43. package/dist/index.d.ts +7 -5
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +6 -4
  46. package/dist/index.js.map +1 -1
  47. package/package.json +1 -1
  48. package/schema/marketing.schema.json +13 -1
  49. package/src/config/schema.ts +14 -2
  50. package/src/footage/compose.ts +33 -12
  51. package/src/footage/draft.ts +2 -2
  52. package/src/footage/failure.ts +44 -0
  53. package/src/footage/film-mix.ts +65 -0
  54. package/src/footage/isolate-ranges.ts +110 -14
  55. package/src/footage/loudness.ts +166 -68
  56. package/src/footage/paid.ts +5 -2
  57. package/src/footage/pipeline.ts +173 -90
  58. package/src/footage/publish.ts +4 -4
  59. package/src/footage/speech-ranges.ts +68 -11
  60. package/src/index.ts +43 -8
package/dist/index.js CHANGED
@@ -51,21 +51,23 @@ export { CAPTION_SAFE_ZONES, applySegmentCaption, findMissingCaptionGlyphs, getC
51
51
  export { CUT_THUMBNAIL, buildCutFrameArgs, chooseCutTransition, chooseCutTransitions, findAutoCuts, measureFrameDifference, } from "./footage/cuts.js";
52
52
  export { MAX_FRAMES, buildFrameArgs, extractFrames, getFrameTimes } from "./footage/frames.js";
53
53
  export { duckingKeyframes, getDuckingOptions, getSpeechSpans, volumeExpression } from "./footage/music.js";
54
- export { END_CARD_SECONDS, FADE_SECONDS, composeFootage, getFootageFilmSeconds, getSegmentScales } from "./footage/compose.js";
54
+ export { END_CARD_SECONDS, FADE_SECONDS, composeFootage, getFootageFilmSeconds, getFootageSfxCues, getSegmentScales, } from "./footage/compose.js";
55
+ export { buildFilmMixArgs } from "./footage/film-mix.js";
55
56
  export { buildCutPreviewArgs, buildLastFrameArgs, buildMusicArgs, buildSpeechArgs, getSpeechCutOptions } from "./footage/render.js";
56
57
  export { FOOTAGE_DRAFT_CAPTION_COLORS, FOOTAGE_DRAFT_FONT, FOOTAGE_DRAFT_WIDTH, buildFootageDraftArgs, buildFootageDraftCaptions, getFootageDraftFrame, planFootageDraft, renderFootageDraft, toAssColor, } from "./footage/draft.js";
57
58
  export { chooseFootageDraftFont, readFontFamilyName } from "./footage/draft-font.js";
58
59
  export { buildPictureConcatArgs, buildPictureList, buildPicturePieceArgs, getPictureFrames, planFootagePicture, } from "./footage/picture.js";
59
- export { DEFAULT_LOUDNESS, buildLoudnessArgs, buildLoudnessMeasureArgs, buildMixArgs, findLoudnessProblems, formatDb, getFirstMixAttempt, getLimiterSlope, getLoudnessFilter, getMixFilter, getMixGain, getMixTolerance, getNextMixAttempt, isSilent, measureLoudness, MIX_ATTEMPTS, MIX_ENCODE_HEADROOM, MIX_LIMITER_SLOPE, MIX_LIMITER_SLOPE_MAX, MIX_LOUDNESS_TOLERANCE, MIX_RETRY_EDGE_MARGIN, normalizeLoudness, readLoudnessMeasurement, } from "./footage/loudness.js";
60
+ export { DEFAULT_LOUDNESS, buildLoudnessArgs, buildLoudnessMeasureArgs, buildMixArgs, findLoudnessProblems, formatDb, getBestGainProbe, getFirstMixCeiling, getLoudnessFilter, getLoudnessVerdict, getMixAim, getMixAttempts, getMixFilter, getMixGain, getMixTolerance, getNextGainProbe, getNextMixCeiling, isSilent, measureLoudness, MIX_AIM_EDGE_MARGIN, MIX_ATTEMPTS, MIX_ENCODE_HEADROOM, MIX_GAIN_PRECISION, MIX_GAIN_PROBES, MIX_LOUDNESS_TOLERANCE, MIX_LOWPASS_HZ, solveMixGain, normalizeLoudness, readLoudnessMeasurement, } from "./footage/loudness.js";
60
61
  export { buildCoverArgs, buildFinishArgs, clampCoverSeconds, findFinishProblems, findFinishVideoProblems, getCoverPath, getDefaultCoverSeconds, isFastStart, isPublishableAudio, isPublishableVideo, PUBLISHABLE_H264_PROFILES, probeFilmFacts, readFilmFacts, readTopLevelBoxes, } from "./footage/publish.js";
61
62
  export { readFfmpegProgressSeconds, runFfmpeg, runProcess, withFfmpegFailureReporting, } from "./footage/process.js";
62
63
  export { FFMPEG_FAILURE_STDERR_LINES, formatFfmpegCommand, splitFilterGraph } from "./footage/ffmpeg-command.js";
63
64
  export { buildFfmpegFailureScript, FFMPEG_FAILURE_FILES, writeFfmpegFailure } from "./footage/ffmpeg-failure.js";
64
65
  export { estimateFootageFilm, estimateSpeechRanges, findCachedStep, getDownloadPath, } from "./footage/paid.js";
65
- export { DEFAULT_SPEECH_RANGE_MARGIN, buildRangeAudioArgs, buildRangeLayArgs, getSpeechRangeCache, getSpeechRangeWindows, planSpeechRanges, } from "./footage/speech-ranges.js";
66
- export { isolateSpeechRanges } from "./footage/isolate-ranges.js";
66
+ export { DEFAULT_SPEECH_RANGE_FADE_MS, DEFAULT_SPEECH_RANGE_MARGIN, buildRangeAudioArgs, buildRangeLayArgs, getSpeechRangeCache, getSpeechRangeFades, getSpeechRangeWindows, planSpeechRanges, } from "./footage/speech-ranges.js";
67
+ export { DEFAULT_SPEECH_RANGE_ATTEMPTS, DEFAULT_SPEECH_RANGE_RETRY_DELAYS_MS, isolateSpeechRanges, } from "./footage/isolate-ranges.js";
67
68
  export { RENDER_MIN_FREE_BYTES, findLowDiskProblems, getFreeBytes, getRenderTempDir } from "./footage/disk.js";
68
69
  export { DRAFT_FILTERS, REQUIRED_DECODERS, REQUIRED_FILTERS, checkFootageTools, findBrowserProblem, readFfmpegListing } from "./footage/tools.js";
69
70
  export { CUTS_FILE, cutFootage, cutFootageFilm, describeCutMeasures, findFootageMusic, getEdlPath, getFrame, getSpeechChainFiles, prepareFootage, getFootageSentences, readEdlFile, readRenderPercent, renderFootage, renderFootageFilm, transcribeFootage, } from "./footage/pipeline.js";
71
+ export { isRetryableFootageFailure } from "./footage/failure.js";
70
72
  export { formatMessage, getMarketingMessages, marketingMessages, } from "./messages/index.js";
71
73
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,oGAAoG;AACpG,uGAAuG;AACvG,wGAAwG;AACxG,wHAAwH;AACxH,wEAAwE;AACxE,qEAAqE;AACrE,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,SAAS,EACT,UAAU,EACV,sBAAsB,EACtB,eAAe,GAKhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,aAAa,EACb,eAAe,GAOhB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,SAAS,EAET,mBAAmB,GAUpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,YAAY,EAAwE,MAAM,oBAAoB,CAAC;AACrI,OAAO,EAAE,kBAAkB,EAA0B,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAsC,MAAM,oBAAoB,CAAC;AAC5G,OAAO,EACL,IAAI,EACJ,cAAc,EACd,UAAU,GAYX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAC1J,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,kBAAkB,GAKnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,wBAAwB,EAA0B,MAAM,uBAAuB,CAAC;AACzI,OAAO,EAAE,qBAAqB,EAA6C,MAAM,iBAAiB,CAAC;AACnG,OAAO,EAAE,iBAAiB,EAAqD,MAAM,sBAAsB,CAAC;AAC5G,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,cAAc,EAAuC,MAAM,kBAAkB,CAAC;AACpJ,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAuD,MAAM,oBAAoB,CAAC;AAC7I,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAoB,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAsD,MAAM,kBAAkB,CAAC;AACjI,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,yBAAyB,EAAsD,MAAM,wBAAwB,CAAC;AAClL,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,EACb,cAAc,EACd,aAAa,EACb,QAAQ,EACR,SAAS,EACT,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,QAAQ,GAkBT,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,WAAW,EACX,SAAS,EACT,mBAAmB,GAOpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,uBAAuB,EACvB,aAAa,GAMd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAsC,MAAM,kBAAkB,CAAC;AACjG,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,SAAS,EAAsB,MAAM,qBAAqB,CAAC;AACnG,OAAO,EAAE,GAAG,EAAE,gBAAgB,EAA2D,MAAM,oBAAoB,CAAC;AACpH,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAMhB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,iBAAiB,EAAuB,MAAM,uBAAuB,CAAC;AACzJ,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAA8C,MAAM,8BAA8B,CAAC;AAClI,OAAO,EACL,SAAS,EACT,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,8BAA8B,EAC9B,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,cAAc,GAef,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,EACd,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,cAAc,EACd,gBAAgB,GAOjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,UAAU,GAKX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,UAAU,EACV,cAAc,GAKf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,aAAa,GAKd,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAAwB,MAAM,0BAA0B,CAAC;AAC5I,OAAO,EACL,iBAAiB,EACjB,WAAW,GAcZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gCAAgC,EAChC,iCAAiC,EACjC,6BAA6B,EAC7B,2BAA2B,EAC3B,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,GAEnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,qBAAqB,EACrB,yBAAyB,GAK1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,iBAAiB,EAAuB,MAAM,uBAAuB,CAAC;AACvH,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,QAAQ,EAAE,oBAAoB,EAAyB,MAAM,oBAAoB,CAAC;AACjI,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,QAAQ,EACR,OAAO,EACP,SAAS,EACT,eAAe,EACf,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,OAAO,EACP,UAAU,EACV,WAAW,GASZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAyD,MAAM,wBAAwB,CAAC;AAChJ,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,GAOb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,sBAAsB,GAGvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAqE,MAAM,qBAAqB,CAAC;AAClK,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAA4C,MAAM,oBAAoB,CAAC;AACrJ,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,gBAAgB,EAAuD,MAAM,sBAAsB,CAAC;AACpL,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,mBAAmB,EAAyB,MAAM,qBAAqB,CAAC;AAC3J,OAAO,EACL,4BAA4B,EAC5B,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,GAQX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAA+B,MAAM,yBAAyB,CAAC;AAClH,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,GAInB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,YAAY,EACZ,oBAAoB,EACpB,QAAQ,EACR,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,GASxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,YAAY,EACZ,sBAAsB,EACtB,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,aAAa,EACb,iBAAiB,GAGlB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,yBAAyB,EACzB,SAAS,EACT,UAAU,EACV,0BAA0B,GAM3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,gBAAgB,EAAsB,MAAM,6BAA6B,CAAC;AACrI,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,kBAAkB,EAA2B,MAAM,6BAA6B,CAAC;AAC1I,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,eAAe,GAKhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GAKjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAkF,MAAM,6BAA6B,CAAC;AAClJ,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,YAAY,EAAE,gBAAgB,EAAwB,MAAM,mBAAmB,CAAC;AACrI,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAA4B,MAAM,oBAAoB,CAAC;AAC5K,OAAO,EACL,SAAS,EACT,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,GAalB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,iBAAiB,GAGlB,MAAM,qBAAqB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softure-ai/marketing-kit",
3
- "version": "0.13.2",
3
+ "version": "0.15.0",
4
4
  "description": "SOFTURE AI marketing kit: a CLI that turns a project's real app into a vertical film (cached voiceover, frame-by-frame recording, HTML composition, hyperframes render) plus per-platform post copy and OG images.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -3021,7 +3021,7 @@
3021
3021
  "target": -14,
3022
3022
  "truePeak": -1
3023
3023
  },
3024
- "description": "The finished film's mix (speech and music), measured after the render, brought to the target by one gain and held under the true peak by a limiter; false leaves the mix as rendered. Default -14 LUFS, -1 dBTP.",
3024
+ "description": "The finished film's mix (speech, music and sound effects), mixed and measured before the frames are rendered, brought to the target by one gain at a fixed true peak ceiling and held under it by a limiter; false leaves the mix as rendered. Default -14 LUFS, -1 dBTP.",
3025
3025
  "anyOf": [
3026
3026
  {
3027
3027
  "type": "boolean",
@@ -3057,6 +3057,18 @@
3057
3057
  "loudness",
3058
3058
  "speech"
3059
3059
  ]
3060
+ },
3061
+ "attempts": {
3062
+ "description": "How many times the mix is encoded and measured before the film fails (1 to 6, default 4); most mixes need one.",
3063
+ "type": "integer",
3064
+ "minimum": 1,
3065
+ "maximum": 6
3066
+ },
3067
+ "warnTolerance": {
3068
+ "description": "A near-miss band in LU (0.2 to 3, at least tolerance): a mix outside target ± tolerance but inside target ± warnTolerance, under the true peak limit, finishes with a warning instead of failing.",
3069
+ "type": "number",
3070
+ "minimum": 0.2,
3071
+ "maximum": 3
3060
3072
  }
3061
3073
  },
3062
3074
  "additionalProperties": false
@@ -634,10 +634,22 @@ const footageSchema = z
634
634
  .enum(["loudness", "speech"])
635
635
  .optional()
636
636
  .describe('"loudness" (default): one gain brings the mix to target; "speech": no gain while the mix measures inside target ± tolerance, so the speech keeps its level whatever the music volume.'),
637
- }),
637
+ attempts: z.number().int().min(1).max(6).optional().describe("How many times the mix is encoded and measured before the film fails (1 to 6, default 4); most mixes need one."),
638
+ warnTolerance: z
639
+ .number()
640
+ .min(0.2)
641
+ .max(3)
642
+ .optional()
643
+ .describe(
644
+ "A near-miss band in LU (0.2 to 3, at least tolerance): a mix outside target ± tolerance but inside target ± warnTolerance, under the true peak limit, finishes with a warning instead of failing.",
645
+ ),
646
+ })
647
+ .refine((mix) => mix.warnTolerance === undefined || mix.warnTolerance >= (mix.tolerance ?? 1), { path: ["warnTolerance"], message: "must be at least tolerance (default 1)" }),
638
648
  ])
639
649
  .default({ target: -14, truePeak: -1 })
640
- .describe("The finished film's mix (speech and music), measured after the render, brought to the target by one gain and held under the true peak by a limiter; false leaves the mix as rendered. Default -14 LUFS, -1 dBTP."),
650
+ .describe(
651
+ "The finished film's mix (speech, music and sound effects), mixed and measured before the frames are rendered, brought to the target by one gain at a fixed true peak ceiling and held under it by a limiter; false leaves the mix as rendered. Default -14 LUFS, -1 dBTP.",
652
+ ),
641
653
  cover: z
642
654
  .union([
643
655
  z.literal(false),
@@ -89,6 +89,38 @@ export function getSegmentZoomEases(edl: Edl, edit: Pick<FootageEdit, "zoomPerce
89
89
  });
90
90
  }
91
91
 
92
+ /** One sound effect the film plays: its file, when it starts, its linear volume and how long it plays, in seconds. */
93
+ export interface FootageSfxCue {
94
+ src: string;
95
+ t: number;
96
+ volume: number;
97
+ dur: number;
98
+ }
99
+
100
+ /**
101
+ * The film's sound effects in film time: a whoosh before every `whoosh` cut, and the end card's whoosh and pop with
102
+ * `isEndCardWhoosh`; an event without a file in `sfx` plays nothing. The composition and the film's mix
103
+ * (`buildFilmMixArgs`) both play these.
104
+ */
105
+ export function getFootageSfxCues(film: FootageFilm, edl: Edl, sfx: Partial<Record<SfxEvent, string>>): FootageSfxCue[] {
106
+ const starts = getSegmentStarts(edl);
107
+ const cutEnd = getEdlDuration(edl);
108
+ const edit = getFootageEdit(film);
109
+ const cues: FootageSfxCue[] = [];
110
+ const play = (event: SfxEvent, t: number, volume: number, dur: number) => {
111
+ const src = sfx[event];
112
+ if (src !== undefined) cues.push({ src, t: r3(Math.max(0, t)), volume, dur });
113
+ };
114
+ edl.segments.forEach((segment, index) => {
115
+ if (segment.transition === "whoosh" && index > 0) play("whoosh", (starts[index] as number) - 0.1, 0.45, 0.57);
116
+ });
117
+ if (film.endCard !== null && edit.isEndCardWhoosh) {
118
+ play("whoosh", cutEnd, 0.3, 0.57);
119
+ play("pop", r3(cutEnd + 0.9), 0.35, 0.72);
120
+ }
121
+ return cues;
122
+ }
123
+
92
124
  export function composeFootage(input: FootageComposeInput): string {
93
125
  const { film, edl, words, frame, colors: c, fonts, assets, caption: captionBox } = input;
94
126
  const starts = getSegmentStarts(edl);
@@ -161,18 +193,7 @@ export function composeFootage(input: FootageComposeInput): string {
161
193
  const captionFit = film.captions && film.captionMaxLines !== undefined ? getCaptionFitScript(film.captionMaxLines, Math.round(captionBox.fontSize * CAPTION_MIN_FONT_SCALE)) : "";
162
194
 
163
195
  // --- Sound ---
164
- const sfx: { src: string; t: number; volume: number; dur: number }[] = [];
165
- const play = (event: SfxEvent, t: number, volume: number, dur: number) => {
166
- const src = assets.sfx[event];
167
- if (src !== undefined) sfx.push({ src, t: r3(Math.max(0, t)), volume, dur });
168
- };
169
- edl.segments.forEach((segment, index) => {
170
- if (segment.transition === "whoosh" && index > 0) play("whoosh", (starts[index] as number) - 0.1, 0.45, 0.57);
171
- });
172
- if (film.endCard !== null && edit.isEndCardWhoosh) {
173
- play("whoosh", cutEnd, 0.3, 0.57);
174
- play("pop", r3(cutEnd + 0.9), 0.35, 0.72);
175
- }
196
+ const sfx = getFootageSfxCues(film, edl, assets.sfx);
176
197
  const audio = [
177
198
  `<audio id="speech" src="${escapeHtml(assets.speech)}" data-start="0" data-duration="${cutEnd}" data-volume="1"></audio>`,
178
199
  ...(assets.music === null ? [] : [`<audio id="music" src="${escapeHtml(assets.music)}" data-start="0" data-duration="${end}" data-volume="1"></audio>`]),
@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
4
4
 
5
5
  import type { CaptionLayout, LayoutOverride } from "../compose/timeline.js";
6
6
  import type { BrandColors } from "../config/colors.js";
7
- import { err, ok } from "../voice/provider.js";
7
+ import { err, ok } from "./failure.js";
8
8
  import type { TimedWord } from "../voice/voiceover.js";
9
9
  import { getCaptionChunkLayouts, getCaptionSpans, getFootageCaptionChunks, getFootageCaptionLayout, isSameCaptionPlace, type CaptionWordsFilm } from "./captions.js";
10
10
  import { getSegmentScales, getSegmentZoomEases } from "./compose.js";
@@ -465,7 +465,7 @@ type DraftMusicSource = { kind: "file"; path: string } | { kind: "none" } | { ki
465
465
  async function findDraftMusic(film: FootageFilm, edl: Edl, clips: PreparedClip[], options: RenderFootageDraftOptions): Promise<FootageResult<DraftMusicSource>> {
466
466
  const source = film.music.source;
467
467
  if (source.kind === "none") return ok({ kind: "none" });
468
- if (source.kind === "file") return existsSync(source.path) ? ok({ kind: "file", path: source.path }) : err(`music: no file at ${source.path}`);
468
+ if (source.kind === "file") return existsSync(source.path) ? ok({ kind: "file", path: source.path }) : err(`music: no file at ${source.path}`, { kind: "input" });
469
469
  const { cacheDir, providers } = options;
470
470
  if (cacheDir === undefined || providers === undefined) {
471
471
  return ok({ kind: "not_cached", reason: "the film's music is generated and the draft was given no cacheDir and providers to find it in the cache" });
@@ -0,0 +1,44 @@
1
+ import type { MixLoudness } from "./loudness.js";
2
+
3
+ /**
4
+ * Why a footage step failed, for an app to act on without reading `error` (issue #1126):
5
+ * - `loudness`: the film's mix or the finished film misses `mixLoudness` (the last measurement; null when the mix
6
+ * measures silent after its gain and limiter). The same inputs fail the same way: no retry.
7
+ * - `publishable`: the finished file fails the container, codec profile or fast start checks (the problems).
8
+ * - `input`: the film, its EDL, fonts, files or settings cannot be used as given. A retry fails the same way.
9
+ * - `process`: anything else (a process that exited, the network, the disk). A retry may succeed.
10
+ * A failed ffmpeg step still throws and an abort still rejects with the signal's reason; neither is a result.
11
+ */
12
+ export type FootageFailure =
13
+ | { kind: "loudness"; loudness: MixLoudness | null }
14
+ | { kind: "publishable"; problems: string[] }
15
+ | { kind: "input" }
16
+ | { kind: "process" };
17
+
18
+ export type FootageFailureKind = FootageFailure["kind"];
19
+
20
+ /** A footage failure: `error` is the sentence for logs, `failure` what the app reads. */
21
+ export interface FootageError {
22
+ ok: false;
23
+ error: string;
24
+ failure: FootageFailure;
25
+ }
26
+
27
+ export type FootageResult<T> = { ok: true; value: T } | FootageError;
28
+
29
+ /** A footage success. */
30
+ export function ok<T>(value: T): { ok: true; value: T } {
31
+ return { ok: true, value };
32
+ }
33
+
34
+ const PROCESS_FAILURE: FootageFailure = { kind: "process" };
35
+
36
+ /** A footage failure with its sentence; without a `failure`, the transient `process` kind. */
37
+ export function err(error: string, failure: FootageFailure = PROCESS_FAILURE): FootageError {
38
+ return { ok: false, error, failure };
39
+ }
40
+
41
+ /** True when running the same step again may succeed (`process`); a gate miss or a bad input fails again. */
42
+ export function isRetryableFootageFailure(failure: FootageFailure): boolean {
43
+ return failure.kind === "process";
44
+ }
@@ -0,0 +1,65 @@
1
+ import type { FootageSfxCue } from "./compose.js";
2
+ import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
3
+
4
+ /**
5
+ * The film's sound mixed by ffmpeg as the composition plays it (every element from its start, at its volume, for its
6
+ * duration, summed without normalization), so the mix stage can bring it to the target and gate it before
7
+ * hyperframes captures a frame (issue #1124). The finished film carries this mix, not the render's own sound.
8
+ */
9
+
10
+ export interface FilmMixInput {
11
+ /** The speech track and how long it plays (the cut's length). */
12
+ speech: { file: string; seconds: number };
13
+ /** The ducked music track and how long it plays (the film's length); null for none. */
14
+ music: { file: string; seconds: number } | null;
15
+ /** The sound effects, their `src` a file ffmpeg can read. */
16
+ sfx: readonly FootageSfxCue[];
17
+ /** The film's length: the mix is padded with silence or cut to it. */
18
+ seconds: number;
19
+ /** A WAV file (32-bit float, 48 kHz stereo). */
20
+ output: string;
21
+ }
22
+
23
+ const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
24
+
25
+ /**
26
+ * The ffmpeg arguments that write the film's mix. The length is bounded three times (the padding's `whole_dur`, the
27
+ * trim and the output's `-t`): a mix that once ran unbounded on CI wrote a 90 GB WAV and filled the disk, so no single
28
+ * filter's end of stream is trusted with it. A film length that is not a positive number is a bug and throws.
29
+ */
30
+ export function buildFilmMixArgs(input: FilmMixInput): string[] {
31
+ if (!Number.isFinite(input.seconds) || input.seconds <= 0) throw new Error(`buildFilmMixArgs: the film's length must be a positive number of seconds, got ${String(input.seconds)}.`);
32
+ const length = String(r3(input.seconds));
33
+ const format = `aresample=${FOOTAGE_SAMPLE_RATE},aformat=sample_fmts=fltp:channel_layouts=stereo`;
34
+ const sources: { file: string; filter: string }[] = [
35
+ { file: input.speech.file, filter: `atrim=duration=${r3(input.speech.seconds)},${format}` },
36
+ ...(input.music === null ? [] : [{ file: input.music.file, filter: `atrim=duration=${r3(input.music.seconds)},${format}` }]),
37
+ ...input.sfx.map((cue) => ({
38
+ file: cue.src,
39
+ filter: `atrim=duration=${r3(cue.dur)},${format},volume=${cue.volume},adelay=delays=${Math.round(cue.t * 1000)}:all=1`,
40
+ })),
41
+ ];
42
+ const chains = sources.map((source, index) => `[${index}:a]${source.filter}[a${index}]`);
43
+ const labels = sources.map((_, index) => `[a${index}]`).join("");
44
+ const mixed = sources.length === 1 ? `[a0]anull` : `${labels}amix=inputs=${sources.length}:duration=longest:normalize=0`;
45
+ const graph = [...chains, `${mixed},apad=whole_dur=${length},atrim=duration=${length}[mix]`].join(";");
46
+ return [
47
+ "-v",
48
+ "error",
49
+ "-y",
50
+ ...sources.flatMap((source) => ["-i", source.file]),
51
+ "-filter_complex",
52
+ graph,
53
+ "-map",
54
+ "[mix]",
55
+ "-t",
56
+ length,
57
+ "-c:a",
58
+ "pcm_f32le",
59
+ "-ar",
60
+ String(FOOTAGE_SAMPLE_RATE),
61
+ "-ac",
62
+ "2",
63
+ input.output,
64
+ ];
65
+ }
@@ -1,7 +1,8 @@
1
1
  import { existsSync, mkdirSync } from "node:fs";
2
2
  import { join } from "node:path";
3
+ import { setTimeout as sleep } from "node:timers/promises";
3
4
 
4
- import { err, ok } from "../voice/provider.js";
5
+ import { err, ok } from "./failure.js";
5
6
  import { probeAudio } from "./audio.js";
6
7
  import { writeCacheFile } from "./cache.js";
7
8
  import type { Edl } from "./edl.js";
@@ -9,30 +10,65 @@ import type { FootageFilm } from "./film.js";
9
10
  import { getClipCacheKey } from "./paid.js";
10
11
  import { getFfmpegReporting, type FootageResult, type FootageRunOptions, type PreparedClip } from "./pipeline.js";
11
12
  import { runFfmpeg, withFfmpegFailureReporting } from "./process.js";
12
- import { toPaidAudio } from "./providers.js";
13
+ import { toPaidAudio, type IsolationProvider, type PaidAudio } from "./providers.js";
13
14
  import {
14
15
  buildRangeAudioArgs,
15
16
  buildRangeLayArgs,
16
17
  getSpeechRangeCache,
17
18
  getSpeechRangeWindows,
18
19
  planSpeechRanges,
20
+ DEFAULT_SPEECH_RANGE_FADE_MS,
19
21
  type LaidRange,
20
22
  type SpeechRange,
23
+ type SpeechRangeCacheResolver,
21
24
  } from "./speech-ranges.js";
22
25
 
23
26
  /**
24
27
  * Voice isolation of only what the cut hears (issue #1087): each talking clip's sound ranges (`planSpeechRanges`) are
25
28
  * cleaned one by one and cached by the clip's identity, the range in milliseconds and the provider, so an unchanged
26
29
  * segment is never paid twice and a changed cut pays only its new ranges. The cleaned ranges are laid back over the
27
- * clip's own sound into one file as long as the clip: the speech map `renderFootage` takes.
30
+ * clip's own sound into one file as long as the clip: the speech map `renderFootage` takes. A range the provider refuses
31
+ * is asked again, and one refused on every attempt keeps the clip's own sound in its window while the others are laid
32
+ * (issue #1127): only a cancel stops the call.
28
33
  */
29
34
 
35
+ /** How often a refused range is asked again: `attempts` in all (default 3), waiting `delaysMs[n]` before attempt n + 2. */
36
+ export interface SpeechRangeRetry {
37
+ /** Attempts per range, at least 1; default `DEFAULT_SPEECH_RANGE_ATTEMPTS` (3). */
38
+ attempts?: number;
39
+ /** Milliseconds before each retry (the last repeats); default `DEFAULT_SPEECH_RANGE_RETRY_DELAYS_MS` (1 s, 2 s). */
40
+ delaysMs?: readonly number[];
41
+ /** Waits `ms`, rejecting when `signal` aborts; default a timer. Injected by tests. */
42
+ wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
43
+ }
44
+
45
+ export const DEFAULT_SPEECH_RANGE_ATTEMPTS = 3;
46
+ export const DEFAULT_SPEECH_RANGE_RETRY_DELAYS_MS: readonly number[] = [1000, 2000];
47
+
30
48
  export type IsolateSpeechRangesOptions = Pick<FootageRunOptions, "buildDir" | "cacheDir" | "providers" | "isCommit" | "signal" | "onCharge" | "onProgress" | "onFfmpegFailure"> & {
31
49
  /** Seconds added on each side of a sound span; default `DEFAULT_SPEECH_RANGE_MARGIN` (0.25). */
32
50
  margin?: number;
51
+ /** Retries of a refused range. */
52
+ retry?: SpeechRangeRetry;
53
+ /** Milliseconds of the linear crossfade at every join; default `DEFAULT_SPEECH_RANGE_FADE_MS` (15), 0 switches at once. */
54
+ fadeMs?: number;
55
+ /** The `item` of a range's charge (e.g. the app's segment id); default the clip id. */
56
+ chargeItem?: (range: SpeechRange) => string;
57
+ /**
58
+ * Where a range's cleaned voice is cached; default `getSpeechRangeCache` (`<cacheDir>/<film>/<key>.isolated.mp3`).
59
+ * An app that already holds paid ranges under its own keys points the block at them.
60
+ */
61
+ rangeCache?: SpeechRangeCacheResolver;
33
62
  log?: (line: string) => void;
34
63
  };
35
64
 
65
+ /** What happened to a range in this call. */
66
+ export type SpeechRangeOutcome =
67
+ | { kind: "cached" }
68
+ | { kind: "bought"; attempts: number }
69
+ | { kind: "failed"; error: string; attempts: number }
70
+ | { kind: "not_bought" };
71
+
36
72
  export interface IsolatedSpeechRange extends SpeechRange {
37
73
  /** The paid cache's key and file of the range's cleaned voice. */
38
74
  cacheKey: string;
@@ -41,6 +77,11 @@ export interface IsolatedSpeechRange extends SpeechRange {
41
77
  cached: boolean;
42
78
  /** Whether it is laid in the clip's speech file (cached, or bought with `isCommit`). */
43
79
  laid: boolean;
80
+ /**
81
+ * `cached`; `bought` in this call; `failed` when the provider refused it on every attempt (its window keeps the
82
+ * clip's own sound); `not_bought` without `isCommit`.
83
+ */
84
+ outcome: SpeechRangeOutcome;
44
85
  }
45
86
 
46
87
  export interface IsolatedSpeech {
@@ -52,8 +93,9 @@ export interface IsolatedSpeech {
52
93
  /**
53
94
  * Cleans the voice of the ranges the cut hears and answers the speech map the render takes (`TranscribeOutcome.speech`).
54
95
  * With `isCommit` every uncached range is bought (`onCharge` step `isolate`, item the clip id, with its `range`);
55
- * without it only cached ranges are laid, a free draft, and `ranges` names what is still missing. Each clip with a laid
56
- * range gets `<buildDir>/audio/<id>.ranges.mp3`.
96
+ * without it only cached ranges are laid, a free draft, and `ranges` names what is still missing. A refused range is
97
+ * retried (`retry`); one refused on every attempt is answered `failed` and the call still succeeds. Each clip with a
98
+ * laid range gets `<buildDir>/audio/<id>.ranges.mp3`, crossfaded at every join (`fadeMs`).
57
99
  */
58
100
  export function isolateSpeechRanges(film: FootageFilm, clips: PreparedClip[], edl: Edl, options: IsolateSpeechRangesOptions): Promise<FootageResult<IsolatedSpeech>> {
59
101
  const log = options.log ?? ((): void => undefined);
@@ -88,9 +130,9 @@ async function runIsolateSpeechRanges(
88
130
  clipKey = await getClipCacheKey(clip.source, clip.clip);
89
131
  clipKeys.set(range.clip, clipKey);
90
132
  }
91
- const cache = getSpeechRangeCache(film.id, clipKey, range, { cacheDir: options.cacheDir, provider: providers.isolation.id });
133
+ const cache = options.rangeCache?.(range, clipKey) ?? getSpeechRangeCache(film.id, clipKey, range, { cacheDir: options.cacheDir, provider: providers.isolation.id });
92
134
  const cached = existsSync(cache.path);
93
- ranges.push({ ...range, cacheKey: cache.key, path: cache.path, cached, laid: cached });
135
+ ranges.push({ ...range, cacheKey: cache.key, path: cache.path, cached, laid: cached, outcome: cached ? { kind: "cached" } : { kind: "not_bought" } });
94
136
  }
95
137
  const buying = options.isCommit ? ranges.filter((range) => !range.cached) : [];
96
138
  const total = buying.reduce((sum, range) => sum + (range.endMs - range.startMs) / 1000, 0);
@@ -110,15 +152,28 @@ async function runIsolateSpeechRanges(
110
152
  await runFfmpeg(`Cutting ${describeRange(range)} for voice isolation`, buildRangeAudioArgs(clip.file, range, input), { ...aborting, output: input });
111
153
  signal?.throwIfAborted();
112
154
  log(`voice isolation (${providers.isolation.id}): ${describeRange(range)}, ${units.toFixed(1)} s.`);
113
- const cleaned = await providers.isolation.isolate({ audio: input, ...aborting });
114
- signal?.throwIfAborted();
115
- if (!cleaned.ok) return err(`${describeRange(range)}: ${cleaned.error}`);
116
- const paid = toPaidAudio(cleaned.value);
155
+ const answer = await isolateWithRetries({
156
+ audio: input,
157
+ isolation: providers.isolation,
158
+ retry: options.retry ?? {},
159
+ ...aborting,
160
+ onRefused: (error, attempt) => {
161
+ log(`voice isolation: ${describeRange(range)} refused (attempt ${String(attempt)}): ${error}`);
162
+ },
163
+ });
164
+ if (!answer.ok) {
165
+ range.outcome = { kind: "failed", error: answer.error, attempts: answer.attempts };
166
+ done += units;
167
+ report(range, index);
168
+ continue;
169
+ }
170
+ const paid = answer.paid;
117
171
  writeCacheFile(range.path, paid.audio);
118
172
  range.laid = true;
173
+ range.outcome = { kind: "bought", attempts: answer.attempts };
119
174
  options.onCharge?.({
120
175
  step: "isolate",
121
- item: range.clip,
176
+ item: options.chargeItem?.(range) ?? range.clip,
122
177
  provider: providers.isolation.id,
123
178
  units,
124
179
  ...(paid.credits === undefined ? {} : { credits: paid.credits }),
@@ -129,7 +184,9 @@ async function runIsolateSpeechRanges(
129
184
  done += units;
130
185
  report(range, index);
131
186
  }
132
- const missing = ranges.filter((range) => !range.laid);
187
+ const failed = ranges.filter((range) => range.outcome.kind === "failed");
188
+ if (failed.length > 0) log(`voice isolation: ${String(failed.length)} range${failed.length === 1 ? "" : "s"} refused, laid with the clip's own sound: ${failed.map(describeRange).join("; ")}.`);
189
+ const missing = ranges.filter((range) => range.outcome.kind === "not_bought");
133
190
  if (missing.length > 0) {
134
191
  const seconds = missing.reduce((sum, range) => sum + (range.endMs - range.startMs) / 1000, 0);
135
192
  log(`voice isolation DRY RUN: ${String(missing.length)} range${missing.length === 1 ? "" : "s"} (${seconds.toFixed(1)} s) not cached, laid with the clip's own sound. Run with --commit to pay.`);
@@ -150,12 +207,51 @@ async function runIsolateSpeechRanges(
150
207
  }
151
208
  const output = join(buildDir, "audio", `${id}.ranges.mp3`);
152
209
  mkdirSync(join(buildDir, "audio"), { recursive: true });
153
- await runFfmpeg(`Laying the cleaned voice over clip ${id}`, buildRangeLayArgs(clip.file, laid, output), { ...aborting, output });
210
+ await runFfmpeg(`Laying the cleaned voice over clip ${id}`, buildRangeLayArgs(clip.file, laid, output, { fadeMs: options.fadeMs ?? DEFAULT_SPEECH_RANGE_FADE_MS }), { ...aborting, output });
154
211
  speech[id] = output;
155
212
  }
156
213
  return ok({ speech, ranges });
157
214
  }
158
215
 
216
+ type IsolationAnswer = { ok: true; paid: PaidAudio; attempts: number } | { ok: false; error: string; attempts: number };
217
+
218
+ /** Asks the provider for one range's cleaned voice, again after each refusal up to `retry.attempts`; a cancel throws. */
219
+ async function isolateWithRetries(input: {
220
+ audio: string;
221
+ isolation: IsolationProvider;
222
+ retry: SpeechRangeRetry;
223
+ signal?: AbortSignal;
224
+ onRefused: (error: string, attempt: number) => void;
225
+ }): Promise<IsolationAnswer> {
226
+ const { audio, isolation, retry, signal, onRefused } = input;
227
+ const attempts = Math.max(1, Math.floor(retry.attempts ?? DEFAULT_SPEECH_RANGE_ATTEMPTS));
228
+ const delays = retry.delaysMs ?? DEFAULT_SPEECH_RANGE_RETRY_DELAYS_MS;
229
+ const wait = retry.wait ?? waitFor;
230
+ let error = "";
231
+ for (let attempt = 1; attempt <= attempts; attempt += 1) {
232
+ if (attempt > 1) {
233
+ await wait(delays[Math.min(attempt - 2, delays.length - 1)] ?? 0, signal);
234
+ signal?.throwIfAborted();
235
+ }
236
+ const cleaned = await isolation.isolate({ audio, ...(signal === undefined ? {} : { signal }) });
237
+ signal?.throwIfAborted();
238
+ if (cleaned.ok) return { ok: true, paid: toPaidAudio(cleaned.value), attempts: attempt };
239
+ error = cleaned.error;
240
+ onRefused(error, attempt);
241
+ }
242
+ return { ok: false, error, attempts };
243
+ }
244
+
245
+ /** Resolves after `ms`, or rejects with the signal's reason when it aborts first. */
246
+ async function waitFor(ms: number, signal?: AbortSignal): Promise<void> {
247
+ try {
248
+ await sleep(ms, undefined, signal === undefined ? {} : { signal });
249
+ } catch (error) {
250
+ signal?.throwIfAborted();
251
+ throw error;
252
+ }
253
+ }
254
+
159
255
  function describeRange(range: SpeechRange): string {
160
256
  return `clip ${range.clip} ${(range.startMs / 1000).toFixed(3)}-${(range.endMs / 1000).toFixed(3)} s`;
161
257
  }