Introduction

// Same code. Both platforms.
const folder = "videos";
const subfolder = "movies";
const filename = "bigbuckbunny.mp4";
const index = "movie_bigbuckbunny";

despia(`localcdn://write?url=http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4&filename=${folder}/${subfolder}/${filename}&index=${index}`);

import { Filesystem, Directory } from '@capacitor/filesystem';

// Write requires Base64 encoding
await Filesystem.writeFile({
  path: 'videos/movie.mp4',
  data: base64Data,
  directory: Directory.Data
});

// Read returns Base64
const result = await Filesystem.readFile({
  path: 'videos/movie.mp4',
  directory: Directory.Data
});

// Playback requires Blob URL conversion
const blob = base64ToBlob(result.data);
const blobUrl = URL.createObjectURL(blob);
videoElement.src = blobUrl;

import despia from 'despia-native';

// Step 1: Set up the callback FIRST
window.contentServerChange = (item) => {
  // This fires when download completes (could be seconds or minutes later)
  console.log("Cached:", item.index, item.local_cdn);
  addToDownloadsList(item);
};

// Step 2: Fire the download (no await, no second argument)
const folder = "videos";
const subfolder = "movies";
const filename = "bigbuckbunny.mp4";
const index = "movie_bigbuckbunny";
const pushMessage = "Big Buck Bunny ready for offline viewing";

despia(
  `localcdn://write?url=http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4&filename=${folder}/${subfolder}/${filename}&index=${index}&push=true&pushmessage="${pushMessage}"`
);
// Returns immediately - download continues in background
// Result comes via contentServerChange callback

{
  "index_full": "videos/movies/bigbuckbunny.mp4",
  "index": "movie_bigbuckbunny",
  "extension": "mp4",
  "local_path": "/var/mobile/.../localcdn/videos/movies/bigbuckbunny.mp4",
  "local_cdn": "http://localhost:7777/localcdn/videos/movies/bigbuckbunny.mp4",
  "cdn": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
  "size": "158008374",
  "status": "cached",
  "created_at": "1709856000"
}

// Read - get file metadata by index ID (this one you CAN await)
const data = await despia(
  `localcdn://read?index=${encodeURIComponent(JSON.stringify(["movie_bigbuckbunny"]))}`,
  ["cdnItems"]
);

const items = data.cdnItems;
console.log(items);

[
  {
    "index_full": "videos/movies/bigbuckbunny.mp4",
    "index": "movie_bigbuckbunny",
    "extension": "mp4",
    "local_path": "/var/mobile/.../localcdn/videos/movies/bigbuckbunny.mp4",
    "local_cdn": "http://localhost:7777/localcdn/videos/movies/bigbuckbunny.mp4",
    "cdn": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
    "size": "158008374",
    "status": "cached",
    "created_at": "1709856000"
  }
]

// Use the local URL for playback
videoElement.src = items[0].local_cdn;

// Delete - remove when no longer needed
despia(`localcdn://delete?index=${encodeURIComponent(JSON.stringify(["video_bigbunny"]))}`);

[
  {
    "index_full": "videos/samples/bigbunny.mp4",
    "index": "video_bigbunny",
    "extension": "mp4",
    "local_cdn": "http://localhost:7777/localcdn/videos/samples/bigbunny.mp4",
    "size": "5242880",
    "status": "cached"
  }
]

// Works in video elements
<video src={items[0].local_cdn} />

// Works in audio elements
<audio src={items[0].local_cdn} />

// Works in image elements
<img src={items[0].local_cdn} />

// Works with fetch
fetch(items[0].local_cdn)

// Delete single file by index ID
despia(`localcdn://delete?index=${encodeURIComponent(JSON.stringify(["tutorial_001"]))}`);

// Delete multiple files
despia(`localcdn://delete?index=${encodeURIComponent(JSON.stringify(["tutorial_001", "tutorial_002"]))}`);

// contentServerChange receives ONE item at a time
// It's called once per download - both foreground completions AND background replays
window.contentServerChange = (item) => {
  console.log("Content ready:", item.index);
  console.log("Local URL:", item.local_cdn);
  
  // Add to your downloads list
  addToDownloadsList(item);
  
  // Show notification
  showToast(`${item.index} is ready for offline use!`);
};

{
  "index_full": "videos/movies/bigbuckbunny.mp4",
  "index": "movie_bigbuckbunny",
  "extension": "mp4",
  "local_path": "/var/mobile/.../localcdn/videos/movies/bigbuckbunny.mp4",
  "local_cdn": "http://localhost:7777/localcdn/videos/movies/bigbuckbunny.mp4",
  "cdn": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
  "size": "158008374",
  "status": "cached",
  "created_at": "1709856000"
}

import despia from 'despia-native';

const downloadedItems = [];

window.contentServerChange = (item) => {
  // Avoid duplicates (in case of replays)
  const existingIndex = downloadedItems.findIndex(i => i.index_full === item.index_full);
  if (existingIndex >= 0) {
    downloadedItems[existingIndex] = item;
  } else {
    downloadedItems.push(item);
    // This is a new download - show notification
    showToast(`${item.index} ready for offline!`);
  }
  
  renderDownloadsList(downloadedItems);
};

// Approach 1: Download from remote URL (supports background)
despia(`localcdn://write?url=${remoteUrl}&filename=${path}&index=${id}`);

// Approach 2: Upload from file input (standard HTTP)
const fd = new FormData();
fd.append("file", fileInput.files[0]);
fetch("http://localhost:7777/api/upload", {
  method: "POST",
  body: fd
});
// Returns: { success: true, fileName: "myfile.mp4", url: "http://localhost:7777/files/myfile.mp4" }