Connect your app to Vistune
Vistune plays videos and music from the user's own drives. It can play yours too: describe your service in a small JSON file and answer five requests, and your users open your clips in Vistune like files from a drive, with frame-by-frame review, compare, drawings, downloads, playlists and sync. Vistune only reads; it never changes or deletes anything on your side, and it runs no code from you.
What the user sees
- Your app shows Connect to Vistune, a link (or QR code) of the form
vistune://connect/source?url=<manifest address>. - Vistune opens, reads your manifest and shows your name, icon and what you offer. The user agrees, signs in the way you chose, and picks the folders to add.
- From then on your files are part of their library: Videos and Music tabs, Search, favorites, playlists, folders, downloads. "Disconnect" in Settings forgets your token and your files.
The manifest
Served as application/json from an https address, for example https://api.example.com/vistune.json.
Keep that address stable: Vistune derives your source's id from it.
{
"format": 1,
"name": "My Club Video",
"icon": "https://api.example.com/icon.png",
"website": "https://example.com",
"api": "https://api.example.com/vistune/v1",
"auth": { "type": "pairing", "hint": "Settings → Vistune in the app" },
"capabilities": ["search", "appFolder"]
}
| Field | Meaning |
|---|---|
format | Always 1. |
name | Up to 60 characters; shown as the provider's name everywhere in Vistune. |
icon, website | Optional, https. Shown on the connect screen. |
api | Base URL of the endpoints below, https, no trailing slash. |
auth | oauth2 (authorization code with PKCE, redirect vistune://oauth), pairing (a one-time code the user types), or none (public). |
capabilities | search and/or appFolder; both optional. |
The API
JSON answers; Vistune sends Authorization: Bearer <token> unless auth is none.
| Request | Answer |
|---|---|
GET {api}/me | { "name", "email" }, optional (404 is fine). |
GET {api}/folders/{id}/items?cursor= | { "items": [...], "nextCursor" }. The root is root. |
GET {api}/items/{id} | One item. |
GET {api}/items/{id}/stream | { "url", "headers", "expiresAt" }: an address that answers byte-range requests. |
GET {api}/search?q= | { "items": [...] }, files only. With search. |
GET / PUT {api}/app-folder/{name} | Vistune's small sync files, if you keep them. With appFolder. |
POST {pairingEndpoint} | { "code", "device" } → { "accessToken", "refreshToken", "expiresIn" }. With pairing. |
An item:
{ "id": "clip-8213", "name": "final-serve.mp4", "type": "file",
"mimeType": "video/mp4", "size": 48213991,
"modifiedAt": "2026-05-01T10:00:00Z", "createdAt": "2026-05-01T09:30:00Z",
"title": "Final · serve", "subtitle": "Ann · 1 May 2026", "durationSec": 92,
"parentId": "event-12", "path": "2026/Finals", "checksum": "sha256:…" }
Only id, name and type (file or folder) are required. Ids must be stable:
they are what favorites and playlists point at. Streams must answer Range requests with 206, be https, and be
MP4, MOV or M4V (H.264 or HEVC) for video, or MP3, M4A, AAC, WAV, FLAC or AIFF for audio.
Try it
- The full specification, with every field and error code: docs/MEDIA_SOURCES.md (JSON Schema: media-source.schema.json).
- A reference server in about 200 lines of Node, offering a folder on your computer:
scripts/demo-source.mjs. - A checker that reports what Vistune would reject:
node scripts/check-source.mjs https://api.example.com/vistune.json.
WebDAV servers
No app needed: Vistune also connects to any WebDAV folder (a NAS, Nextcloud, a home server) under Settings → Connected
apps & servers. It reads the folder like a drive and writes only its own .vistune sync folder, if sync is
turned on for that server.
What Vistune promises
- Read-only. No endpoint creates, changes or deletes your data; the one exception is the
PUTof its own sync files when the user chose your service for sync. - Tokens stay in the iOS Keychain on the user's device. Nothing about your service reaches Vistune's developer.
- Your name appears only as the manifest's
name. Vistune contains no partner-specific code.
Questions: ondrejstrnad@gmail.com.