Format paczki .storyflow

Wersja schematu 1 · propozycja w fazie budowy; może się zmienić przed wydaniem 1.0

Paczka .storyflow przenosi cały projekt Tellavio między urządzeniami: scenariusz, nagrane podejścia, zaimportowane dźwięki i ustawienia montażu. Ten opis jest dla zespołu i dla przyszłych integracji.

Budowa archiwum

To zwykłe archiwum ZIP. Rozszerzenie .storyflow identyfikuje format, a nie szyfrowanie: zawartość nie jest zaszyfrowana. W katalogu assets/ leżą niezmienione oryginały audio; nazwa pliku to identyfikator zasobu.

project.storyflow   (ZIP)
├── manifest.json
└── assets/
    ├── <assetId>.wav
    ├── <assetId>.m4a
    └── <assetId>.mp3

manifest.json

Manifest opisuje paczkę i zawiera dane projektu bez ścieżek absolutnych. Czasy w danych montażu są liczone w próbkach przy 48 kHz.

{
  "schemaVersion": 1,
  "app": { "name": "StoryFlow", "version": "0.1.0" },
  "projectId": "…",
  "sourceRevision": 42,
  "createdAt": "2026-10-05T12:00:00Z",
  "completeness": "all_takes",
  "assets": [
    { "path": "assets/9f1c….wav", "sha256": "…", "bytes": 1234567, "mime": "audio/wav" }
  ],
  "project": { "…": "…" },
  "chapters": [], "segments": [], "takes": [], "markers": [], "clips": [],
  "templateSnapshot": {}
}

Pola manifestu i ich znaczenie
Pole	Znaczenie
`schemaVersion`	Wersja schematu paczki (liczba całkowita). Obecnie 1.
`app`	Nazwa i wersja aplikacji, która utworzyła paczkę.
`projectId`	Identyfikator projektu na urządzeniu źródłowym. Import tworzy domyślnie nowy projekt z nowym ID.
`sourceRevision`	Rewizja projektu w chwili eksportu paczki.
`createdAt`	Czas utworzenia paczki (ISO 8601, UTC).
`completeness`	all_takes: wszystkie podejścia, pełna historia; used_only: tylko podejścia użyte w montażu, aplikacja oznacza to jako niepełną kopię historii.
`assets`	Lista plików z assets/: ścieżka względna, suma SHA-256, rozmiar w bajtach i typ MIME.
`project`	Dane projektu (tytuł, ustawienia) bez ścieżek absolutnych.
`chapters, segments, takes, markers, clips`	Rozdziały, fragmenty (segments), podejścia (takes), znaczniki (markers) i klipy montażu (clips).
`templateSnapshot`	Migawka szablonu oprawy użytego w projekcie, aby paczka nie zależała od szablonów na urządzeniu docelowym.

Zasady importu

Archiwum jest rozpakowywane do obszaru tymczasowego i weryfikowane, zanim cokolwiek trafi do projektów.
Wpisy ze ścieżką zawierającą .., ścieżki absolutne i duplikaty ścieżek są odrzucane.
Obowiązuje limit rozmiaru po rozpakowaniu i liczby wpisów (ochrona przed zip bomb).
Suma SHA-256 i rozmiar każdego zasobu muszą zgadzać się z manifestem.
Paczka z nowszym schemaVersion, niż obsługuje aplikacja, jest odrzucana w całości, nie częściowo.
Brakujący lub uszkodzony zasób jest wymieniany w raporcie. Nigdy nie jest zastępowany ciszą.
Domyślnie paczka jest importowana jako nowa kopia projektu. Zastąpienie istniejącego projektu wymaga potwierdzenia i zachowuje jego poprzednią wersję.
Projekt jest zatwierdzany transakcyjnie: albo cały, albo wcale.

Prywatność

Paczka może zawierać nieudane podejścia i prywatne notatki. Przed udostępnieniem aplikacja pokazuje, co znajdzie się w paczce. Gotowy eksport audio (M4A, WAV) to coś innego niż paczka: nie zawiera notatek ani podejść.

Wersjonowanie

Zmiana schemaVersion następuje tylko wtedy, gdy nowa wersja aplikacji nadal importuje wszystkie starsze paczki. Pytania o format i integracje: kontakt@tellavio.com.