@eluvio/elv-client-js 4.2.14 → 4.2.16

package/utilities/MezDownloadMp4.js

@@ -0,0 +1,177 @@
+// Utility that accepts an object ID and generates a download URL
+
+const { NewOpt } = require("./lib/options");
+const Utility = require("./lib/Utility");
+const path = require("path");
+const fs = require("fs");
+const https = require("https");
+
+const ArgOutfile = require("./lib/concerns/ArgOutfile");
+const ExistObj = require("./lib/concerns/ExistObj");
+const FabricObject = require("./lib/concerns/FabricObject");
+const DownloadFile = require("./lib/downloadFile");
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const sanitizeFilename = (name, fallback) => {
+  if (!name) return fallback;
+  return name
+    .replace(/\s+/g, "_")
+    .replace(/\//g, "_")
+    .replace(/ - /g, "-")
+};
+
+class MezDownloadMp4 extends Utility {
+  blueprint() {
+    return {
+      concerns: [ArgOutfile, ExistObj, FabricObject],
+      options: [
+        NewOpt("versionHash", {
+          descTemplate: "specific versionHash to download (optional)",
+          type: "string"
+        }),
+        NewOpt("offering", {
+          descTemplate: "Offering name to use, defaults to 'default'",
+          type: "string"
+        }),
+        NewOpt("format", {
+          descTemplate: "Format to request (default mp4)",
+          type: "string"
+        }),
+        NewOpt("downloadDir", {
+          descTemplate: "Directory to save downloaded file",
+          type: "string"
+        })
+      ]
+    };
+  }
+
+  header() {
+    return `Download file for object ${this.args.objectId}`;
+  }
+
+  async body() {
+    const { libraryId, objectId } = await this.concerns.ExistObj.argsProc();
+    const client = await this.concerns.Client.get();
+
+    // -----------------------
+    // Determine versionHash
+    // -----------------------
+    const versionHash = await this.concerns.FabricObject.latestVersionHash({
+      libraryId,
+      objectId
+    });
+
+    const offeringName = this.args.offering || "default";
+    const format = this.args.format || "mp4";
+
+    try {
+      // Start media download job
+      const response = await client.MakeFileServiceRequest({
+        versionHash,
+        path: "/call/media/files",
+        method: "POST",
+        body: {
+          format,
+          offering: offeringName
+        }
+      });
+
+      const jobId = response.job_id;
+
+      // Poll job progress
+      let status;
+      do {
+        await sleep(2000);
+        status = await client.MakeFileServiceRequest({
+          versionHash,
+          path: `/call/media/files/${jobId}`
+        });
+
+        this.logger.log(`${(status?.progress || 0).toFixed(1)} / 100`);
+      } while (status?.status !== "completed");
+
+      // Clean filename
+      const filename = sanitizeFilename(status.filename, "file_download");
+
+      // Build download URL
+      const downloadUrl = await client.FabricUrl({
+        versionHash,
+        call: `/media/files/${jobId}/download`,
+        service: "files",
+        queryParams: {
+          "header-x_set_content_disposition": `attachment; filename=${filename}`
+        }
+      });
+
+      const output = {
+        libraryId,
+        objectId,
+        versionHash,
+        jobId,
+        filename,
+        downloadUrl
+      };
+
+      // Display
+      this.logger.log("\n=== Download Info ===\n");
+      this.logger.logTable([{
+        "Version Hash": output.versionHash,
+        "Filename": output.filename
+      }]);
+      this.logger.log("Download URL:\n", output.downloadUrl, "\n");
+
+      // -----------------------
+      // HTTPS download with progress bar
+      // -----------------------
+      if (downloadUrl) {
+
+        const targetDir = this.args.downloadDir
+          ? path.resolve(this.args.downloadDir)
+          : process.cwd();
+
+        if (!fs.existsSync(targetDir)) {
+          fs.mkdirSync(targetDir, { recursive: true });
+        }
+
+        const outputFile = path.join(targetDir, output.filename || "download.mp4");
+
+        this.logger.log(`Downloading via https → ${outputFile}\n`);
+
+        try {
+          await DownloadFile({
+            url: downloadUrl,
+            dest: outputFile,
+            logger: this.logger,
+            maxRedirects: 5,
+          });
+
+          this.logger.log(`\nDownload complete: ${outputFile}`);
+        } catch (err) {
+          this.logger.error("\nHTTPS download failed:", err.message);
+        }
+      }
+
+      // -----------------------
+      // Outfile support
+      // -----------------------
+      if (this.args.outfile) {
+        if (this.args.json) {
+          this.concerns.ArgOutfile.writeJson({ obj: output });
+        } else {
+          this.concerns.ArgOutfile.writeTable({ list: [output] });
+        }
+      }
+
+    } catch (error) {
+      this.logger.error(error);
+      this.logger.error(JSON.stringify(error, null, 2));
+      throw error;
+    }
+  }
+}
+
+if (require.main === module) {
+  Utility.cmdLineInvoke(MezDownloadMp4);
+} else {
+  module.exports = MezDownloadMp4;
+}

package/utilities/lib/DownloadFile.js

@@ -0,0 +1,88 @@
+const fs = require("fs");
+const https = require("https");
+
+/**
+ * Download a file over HTTPS with redirect handling and progress reporting.
+ *
+ * @param {Object} params
+ * @param {string} params.url - Initial download URL
+ * @param {string} params.dest - Destination file path
+ * @param {Object} [params.logger=console] - Logger with log/error methods
+ * @param {number} [params.maxRedirects=5] - Maximum redirect depth
+ * @returns {Promise<void>}
+ */
+const DownloadFile = ({
+  url,
+  dest,
+  logger = console,
+  maxRedirects = 5
+}) => {
+  const download = (currentUrl, redirects = 0) =>
+    new Promise((resolve, reject) => {
+      if (redirects > maxRedirects) {
+        return reject(new Error("Too many redirects"));
+      }
+
+      https.get(currentUrl, res => {
+
+        // Handle redirects
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          const nextUrl = res.headers.location.startsWith("http")
+            ? res.headers.location
+            : new URL(res.headers.location, currentUrl).href;
+
+          logger.log(`Redirected → ${nextUrl}`);
+          return resolve(download(nextUrl, redirects + 1));
+        }
+
+        if (res.statusCode !== 200) {
+          return reject(new Error(`Download failed (HTTP ${res.statusCode})`));
+        }
+
+        const totalSize = parseInt(res.headers["content-length"] || "0", 10);
+        let downloaded = 0;
+
+        const writeStream = fs.createWriteStream(dest);
+
+        // Progress reporting
+        res.on("data", chunk => {
+          downloaded += chunk.length;
+
+          if (totalSize > 0) {
+            const percent = (downloaded / totalSize) * 100;
+            const mbDownloaded = (downloaded / (1024 * 1024)).toFixed(2);
+            const mbTotal = (totalSize / (1024 * 1024)).toFixed(2);
+
+            const barLength = 30;
+            const filled = Math.round((percent / 100) * barLength);
+            const bar = "█".repeat(filled) + "░".repeat(barLength - filled);
+
+            process.stdout.write(
+              `\r${bar} ${percent.toFixed(1)}%  (${mbDownloaded} MB / ${mbTotal} MB)`
+            );
+          } else {
+            process.stdout.write(
+              `\rDownloaded ${(downloaded / (1024 * 1024)).toFixed(2)} MB`
+            );
+          }
+        });
+
+        res.on("end", () => process.stdout.write("\n"));
+
+        res.pipe(writeStream);
+
+        writeStream.on("finish", () => {
+          writeStream.close(resolve);
+        });
+
+        writeStream.on("error", err => {
+          fs.unlink(dest, () => reject(err));
+        });
+
+      }).on("error", reject);
+    });
+
+  return download(url);
+};
+
+module.exports = DownloadFile;

package/utilities/lib/FrameAccurateVideo.js

@@ -0,0 +1,431 @@
+// copied from 
+// https://github.com/eluv-io/elv-video-editor/blob/4408dd5a98536a13d16f80d2bca943077289765c/src/utils/FrameAccurateVideo.js
+// (no changes made)
+
+// import Fraction from "fraction.js";
+const Fraction = require("fraction.js");
+
+const FrameRateNumerator = {
+  NTSC: 30000,
+  NTSCFilm: 24000,
+  NTSCHD: 60000,
+  PAL: 25,
+  PALHD: 50,
+  Film: 24,
+  Web: 30,
+  High: 60
+};
+
+const FrameRateDenominator = {
+  NTSC: 1001,
+  NTSCFilm: 1001,
+  NTSCHD: 1001,
+  PAL: 1,
+  PALHD: 1,
+  Film: 1,
+  Web: 1,
+  High: 1
+};
+
+const FrameRates = {
+  NTSC: Fraction(FrameRateNumerator["NTSC"]).div(FrameRateDenominator["NTSC"]),
+  NTSCFilm: Fraction(FrameRateNumerator["NTSCFilm"]).div(FrameRateDenominator["NTSC"]),
+  NTSCHD: Fraction(FrameRateNumerator["NTSCHD"]).div(FrameRateDenominator["NTSCHD"]),
+  PAL: Fraction(25),
+  PALHD: Fraction(50),
+  Film: Fraction(24),
+  Web: Fraction(30),
+  High: Fraction(60)
+};
+
+/**
+ * FrameAccurateVideo constructor.
+ *
+ * Initializes a video wrapper that supports frame-accurate timing based on a
+ * specified frame rate. Handles drop-frame logic automatically for NTSC-based
+ * frame rates and optionally registers a time-update callback on the video.
+ *
+ * @param {Object} params
+ * @param {HTMLVideoElement} params.video - Video element to track.
+ * @param {number} params.frameRate - Nominal frame rate (e.g. 29.97, 30).
+ * @param {Object} params.frameRateRat - Rational frame rate representation.
+ * @param {boolean} [params.dropFrame=false] - Enable drop-frame timecode (only valid for NTSC rates).
+ * @param {Function} params.callback - Callback invoked on frame/time updates.
+ */
+class FrameAccurateVideo {
+  constructor({video, frameRate, frameRateRat, dropFrame=false, callback}) {
+    this.video = video;
+    this.SetFrameRate({rate: frameRate, rateRat: frameRateRat});
+    this.callback = callback;
+
+    // Only set drop frame if appropriate based on frame rate
+    const frameRateKey = FrameAccurateVideo.FractionToRateKey(`${this.frameRateNumerator}/${this.frameRateDenominator}`);
+    this.dropFrame = dropFrame && ["NTSC", "NTSCFilm", "NTSCHD"].includes(frameRateKey);
+
+    if(this.video && callback) {
+      this.RegisterCallback();
+    }
+
+    this.TimeToString = FrameAccurateVideo.TimeToString.bind(this);
+    this.Update = this.Update.bind(this);
+  }
+
+  static FractionToRateKey(input) {
+    let rate = input;
+    if(typeof input === "string") {
+      if(input.includes("/")) {
+        rate = input.split("/");
+        rate = rate[0] / rate[1];
+      } else {
+        rate = parseFloat(input);
+      }
+    }
+
+    switch(rate) {
+      case 24:
+        return "Film";
+      case 25:
+        return "PAL";
+      case 30:
+        return "Web";
+      case 50:
+        return "PALHD";
+      case 60:
+        return "High";
+      default:
+        if(Math.abs(24 - rate) < 0.1) {
+          return "NTSCFilm";
+        } else if(Math.abs(30 - rate) < 0.1) {
+          return "NTSC";
+        } else if(Math.abs(60 - rate) < 0.1) {
+          return "NTSCHD";
+        }
+
+        console.error(`Unknown playback rate: ${input}`);
+
+        FrameRateNumerator.Unknown = parseInt(input.split("/")[0]);
+        FrameRateDenominator.Unknown = parseInt(input.split("/")[1]);
+        FrameRates.Unknown = rate;
+        return "Unknown";
+    }
+  }
+
+  static TimeToString({time, includeFractionalSeconds, format="description"}) {
+    let seconds = Fraction(time);
+    const hours = seconds.div(3600).floor().valueOf();
+    const minutes = seconds.div(60).mod(60).floor(0).valueOf();
+    seconds = seconds.mod(60);
+
+    let string = "";
+    if(format === "smpte") {
+      string = `${hours.toString().padStart(2, "0")}:${minutes.toString().padStart(2, "0")}`;
+      string += `:${seconds.floor().valueOf().toString().padStart(2, "0")}`;
+
+      if(includeFractionalSeconds && seconds.floor().valueOf() !== seconds.valueOf()) {
+        string += `.${parseFloat(seconds.valueOf().toFixed(4).toString().split(".")[1])}`;
+      }
+
+      return string;
+    }
+
+    if(hours > 0) {
+      string += `${hours}h `;
+    }
+
+    if(minutes > 0) {
+      string += `${minutes}m `;
+    }
+
+    if(!string || seconds > 0) {
+      if(includeFractionalSeconds) {
+        string += `${parseFloat(seconds.valueOf().toFixed(4))}s`;
+      } else {
+        string += `${seconds.floor().valueOf()}s`;
+      }
+    }
+
+    return string.trim();
+  }
+
+  /* Conversion utility methods */
+
+  static ParseRat(str) {
+    if(str.includes("/")) {
+      const num = parseInt(str.split("/")[0]);
+      const denom = parseInt(str.split("/")[1]);
+
+      return Number((num / denom).toFixed(3));
+    } else {
+      return parseInt(str);
+    }
+  }
+
+  SetFrameRate({rate, rateRat}) {
+    let num, denom;
+    if(rateRat) {
+      if(rateRat.includes("/")) {
+        num = parseInt(rateRat.split("/")[0]);
+        denom = parseInt(rateRat.split("/")[1]);
+      } else {
+        num = parseInt(rateRat);
+        denom = 1;
+      }
+
+      rate = Fraction(num).div(denom);
+    } else {
+      const rateKey = FrameAccurateVideo.FractionToRateKey(this.frameRate);
+      num = FrameRateNumerator[rateKey];
+      denom = FrameRateDenominator[rateKey];
+    }
+
+    this.frameRate = Fraction(rate);
+    this.frameRateNumerator = num;
+    this.frameRateDenominator = denom;
+  }
+
+  RatToFrame(rat) {
+    const [numerator, denominator] = rat.split("/");
+    const time = denominator ? Fraction(numerator).div(denominator) : numerator;
+
+    return this.TimeToFrame(time);
+  }
+
+  FrameToRat(frame) {
+    return `${frame * this.frameRateDenominator}/${this.frameRateNumerator}`;
+  }
+
+  FrameToTime(frame) {
+    if(frame === 0) { return 0; }
+
+    return Fraction(frame).div(this.frameRate).valueOf();
+  }
+
+  FrameToSMPTE(frame) {
+    return this.SMPTE(frame);
+  }
+
+  ProgressToTime(progress, duration=0) {
+    return Fraction(progress).mul(duration).valueOf();
+  }
+
+  ProgressToSMPTE(progress, duration=0) {
+    return this.TimeToSMPTE(Fraction(progress).mul(duration));
+  }
+
+  TimeToFrame(time, round=false) {
+    const frame = Fraction(time || 0).mul(this.frameRate);
+
+    if(round) {
+      return frame.round().valueOf();
+    } else {
+      return frame.floor().valueOf();
+    }
+  }
+
+  TimeToSMPTE(time) {
+    return this.SMPTE(this.TimeToFrame(time));
+  }
+
+  SMPTEToFrame(smpte) {
+    const components = smpte.split(/[:;]/).reverse();
+
+    const frames = Fraction(components[0]);
+    const seconds = Fraction(components[1]);
+    const minutes = Fraction(components[2]);
+    const hours = Fraction(components[3] || 0);
+
+    let skippedFrames = 0;
+    if(this.dropFrame) {
+      const skippedFramesPerMinute = this.frameRate.equals(FrameRates.NTSCHD) ? Fraction(4) : Fraction(2);
+      const totalMinutes = minutes.add(hours.mul(60));
+      const tenMinutes = totalMinutes.div(10).floor();
+      skippedFrames = totalMinutes.mul(skippedFramesPerMinute)
+        .sub(tenMinutes.mul(skippedFramesPerMinute));
+    }
+
+    return frames
+      .add(seconds.mul(this.frameRate.round()))
+      .add(minutes.mul(this.frameRate.round()).mul(60))
+      .add(hours.mul(this.frameRate.round()).mul(60).mul(60))
+      .sub(skippedFrames)
+      .valueOf();
+  }
+
+  SMPTEToTime(smpte) {
+    const frame = this.SMPTEToFrame(smpte);
+
+    return Fraction(frame).div(this.frameRate).valueOf();
+  }
+
+  /* Time Calculations */
+
+  Frame() {
+    return this.TimeToFrame(this.video?.currentTime || 0);
+  }
+
+  Pad(fraction) {
+    fraction = fraction.valueOf();
+    return fraction < 10 ? `0${fraction}` : fraction;
+  }
+
+  SMPTE(f) {
+    let frame = (typeof f !== "undefined" ? Fraction(f) : Fraction(this.Frame())).floor();
+    const frameRate = this.frameRate.round();
+
+    if(this.dropFrame) {
+      const framesPerMinute = this.frameRate.equals(FrameRates.NTSCHD) ? Fraction(4) : Fraction(2);
+      const tenMinutes = Fraction("17982").mul(framesPerMinute).div(2);
+      const oneMinute = Fraction("1798").mul(framesPerMinute).div(2);
+
+      const tenMinuteIntervals = frame.div(tenMinutes).floor();
+      let framesSinceLastInterval = frame.mod(tenMinutes);
+
+      // If framesSinceLastInterval < framesPerMinute
+      if(framesSinceLastInterval.compare(framesPerMinute) < 0) {
+        // This is where the jump from :59:29 -> :00:02 or :59:59 -> :00:04 happens
+        framesSinceLastInterval = framesSinceLastInterval.add(framesPerMinute);
+      }
+
+      frame = frame.add(
+        framesPerMinute.mul(tenMinuteIntervals).mul("9").add(
+          framesPerMinute.mul((framesSinceLastInterval.sub(framesPerMinute)).div(oneMinute).floor())
+        )
+      );
+    }
+
+    const hours = frame.div(frameRate.mul(3600)).mod(24).floor();
+    const minutes = frame.div(frameRate.mul(60)).mod(60).floor();
+    const seconds = frame.div(frameRate).mod(60).floor();
+    const frames = frame.mod(frameRate).floor();
+
+    const lastColon = this.dropFrame ? ";" : ":";
+
+    return `${this.Pad(hours)}:${this.Pad(minutes)}:${this.Pad(seconds)}${lastColon}${this.Pad(frames)}`;
+  }
+
+  TotalFrames(duration=0) {
+    return Math.floor(Fraction(duration).mul(this.frameRate).valueOf());
+  }
+
+  FrameToString({frame, includeFractionalSeconds}) {
+    let [hours, minutes, seconds, frames] = this.SMPTE(frame).split(":").map(e => parseInt(e));
+
+    if(includeFractionalSeconds) {
+      seconds = Fraction(frames).div(this.frameRate).add(seconds).round(4);
+    }
+
+    let string = "";
+    if(hours > 0) {
+      string += `${hours}h `;
+    }
+
+    if(minutes > 0) {
+      string += `${minutes}m `;
+    }
+
+    if(seconds > 0 || !string) {
+      string += `${seconds}s`;
+    }
+
+    return string.trim();
+  }
+
+  /* Controls */
+
+  SeekForward(frames=1) {
+    const frame = this.Frame();
+    this.Seek(frame.add(frames));
+  }
+
+  SeekBackward(frames=1) {
+    const frame = Fraction(this.Frame());
+    this.Seek(frame.sub(frames));
+  }
+
+  SeekPercentage(percent, duration) {
+    this.Seek(Fraction(this.TotalFrames(duration)).mul(percent));
+  }
+
+  Seek(frame) {
+    if(!this.video) { return; }
+
+    // Whenever seeking, stop comfortably in the middle of a frame
+    frame = Fraction(frame).floor().add(0.5);
+
+    this.video.currentTime = frame.div(this.frameRate).valueOf().toFixed(3);
+  }
+
+  /* Callbacks */
+
+  Update() {
+    if(this.callback) {
+      this.callback({
+        frame: this.Frame().valueOf(),
+        smpte: this.SMPTE()
+      });
+    }
+  }
+
+  RegisterCallback() {
+    if(!this.video) { return; }
+
+    this.Update();
+
+    this.video.onseeked = (event) => this.Update(event);
+    this.video.onseeking = (event) => this.Update(event);
+    this.video.onplay = () => this.AddListener();
+    this.video.onpause = () => {
+      // On pause, seek to the nearest frame
+      this.Seek(this.Frame() + (this.frameRate.valueOf() > 30 ? 2 : 1));
+      this.RemoveListener();
+    };
+
+    this.video.onended = () => this.RemoveListener();
+    this.video.onratechange = () => {
+      // Update listener rate
+      if(this.listener) {
+        this.RemoveListener();
+        this.AddListener();
+      }
+    };
+  }
+
+  RemoveCallback() {
+    if(!this.video) { return; }
+
+    this.video.onseeked = undefined;
+    this.video.onseeking = undefined;
+    this.video.onplay = undefined;
+    this.video.onpause = undefined;
+    this.video.onended = undefined;
+    this.video.onratechange = undefined;
+  }
+
+  AddListener() {
+    if(!this.video) { return; }
+
+    // Call once per frame - possible range 10hz - 50hz               Prevent division by zero
+    const fps = Fraction(this.video.playbackRate).mul(this.frameRate).add(Fraction("0.00001"));
+    const interval = Math.min(Math.max(Fraction(1000).div(fps).valueOf(), 20), 100);
+
+    this.listener = setInterval(() => {
+      if(this.video.paused || this.video.ended) {
+        return;
+      }
+
+      this.Update();
+    }, interval);
+  }
+
+  RemoveListener() {
+    if(this.listener) {
+      clearInterval(this.listener);
+    }
+
+    this.Update();
+  }
+}
+
+module.exports = {
+  FrameAccurateVideo
+};

package/utilities/lib/concerns/Client.js

@@ -31,6 +31,11 @@ const blueprint = {
       descTemplate: "Geographic region for the fabric nodes.",
       group: "API",
       type: "string"
+    }),
+    NewOpt("node", {
+      descTemplate: "Pin all fabric and file-service requests to a specific node hostname or URL (e.g. host-76-74-28-240.contentfabric.io). Overrides the nodes returned by the config URL.",
+      group: "API",
+      type: "string"
     })
   ]
 };