Storage & media delivery

TubePress keeps every uploaded video, its transcoded renditions and its preview assets on disk, and can transparently offload them to one or more external storage servers. This page explains where files live, how the media storages system spreads them across backends, and how media reaches viewers without exposing your raw files.

Storage is configured under /admin/settings?tab=storage. You can run entirely from the local disk, or add FTP, S3-compatible and WebDAV backends and let TubePress fill them in turn.

How TubePress stores media

Uploads live under public/uploads/. Every video gets its own folder — the video's video_folder — which holds the original source alongside each rendition the transcoder produces and the small assets the player needs:

public/uploads/
  videos/
    a1b2c3d4.../        one folder per video (video_folder)
      video.mp4         original upload (source)
      video_1080p.mp4   processed source rendition
      video_720p.mp4    transcoded rendition
      video_480p.mp4    transcoded rendition
      timeline.vtt      scrub-preview sprite map
      preview.mp4       hover-preview clip
  thumbnails/           poster images
  watermark/            watermark PNG
  intros/               pre-roll / post-roll clips
  branding/             logo, favicon, background

The transcoder discovers the source by scanning for the highest video_<height>p.mp4 file, falling back to a raw video.mp4, .webm or .ogg. Lower renditions are written into the same folder, so a single directory is everything a video needs. See Transcoding for how those renditions are generated.

External storage servers

The media storages system lets you register any number of backends. New videos always go to the default storage; when a storage passes its disk threshold, TubePress automatically switches new uploads to the next available one. Existing videos keep serving from wherever they were written, because each video records its own storage_id.

Four backend types are supported — nothing else:

Every remote storage also carries a few operational settings:

Adding a storage backend

1. Open the storage editor. Go to /admin/settings?tab=storage and click Add Storage.
2. Pick a type and name it. Choose Local, FTP, S3 or WebDAV. The form swaps to show only the fields that type needs.
3. Enter the media URL and credentials. Set the public Media URL, then the host/keys/path for the backend. Leave a password blank when editing to keep the stored one.
4. Set the operational options. Choose the status, the max disk usage threshold, and whether to sign URLs.
5. Test and save. Saving first runs a connection test (and a monitor-script check if you supplied one). Fix any failed check, then save. Optionally mark it the default so new uploads land there.

The storage monitor

For remote backends, TubePress can track disk space and health using a tiny PHP script you install on the storage box. In the storage editor's Disk Monitoring panel, click Download monitor script (served from /api/storage-monitor-download), upload it to your remote server, then paste its public URL back into the Monitor script URL field.

Once connected, the editor shows live disk usage and the last check time, and the auto-switch threshold uses those readings to know when a backend is full. The script is keyed so only your CMS can query it.

Secure media delivery

When Secure URLs is on for a storage, TubePress never hands out a direct file path. Instead it signs a short, time-limited link routed through /media/:

/media/{token}/{expires}/{path}

The token is re-computed and checked server-side on every request. For a local storage TubePress streams the file itself with HTTP range support (so seeking works); for a remote storage it verifies the token and then issues a 302 redirect to the file on your CDN. Raw video is also rate-limited at the web-server layer: the storage editor generates a ready-to-paste Nginx snippet that caps streaming after the first couple of megabytes, while letting transcode workers pull at full speed with a key.

CDN & Cloudflare

TubePress is built to sit comfortably behind Cloudflare. Two things matter:

• Chunked uploads bypass the 100 MB limit. Transcode results are streamed back to the CMS in pieces via /api/transcode-upload-chunk, so individual requests stay under Cloudflare's free-tier 100 MB cap no matter how large the rendition is.
• Long-cache, cache-busted assets. Static assets are served with long, immutable cache headers and busted by a version query on each release, so a proxy can cache aggressively without ever serving a stale file.

The per-storage Nginx snippet adds sensible expires headers for video and the optional /media/ internal location used by secure local delivery, so you can drop it straight into your site config.

Next steps