> For the complete documentation index, see [llms.txt](https://astroport-1.gitbook.io/astroport.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://astroport-1.gitbook.io/astroport.one/docs/reference/info_json_formats.md).

# info.json Formats - STANDARDIZED SPECIFICATION v2.0

This document describes the **standardized format** of `info.json` files generated by `upload2ipfs.sh`.

## 🔄 BREAKING CHANGE - Version 2.0

**This specification introduces a breaking change from v1.0:**

* YouTube metadata moved from root level to `source.youtube` section
* TMDB metadata standardized in `source.tmdb` section
* Media metadata standardized with consistent field names
* Use `TUBE.manager.sh cleanup` to remove v1.0 events

## Base Structure (Always Present)

All `info.json` files share this common structure:

```json
{
  "protocol": {
    "name": "UPlanet File Management Contract",
    "version": "2.0.0",
    "specification": "https://github.com/papiche/Astroport.ONE/blob/main/Astroport.ONE/docs/UPlanet_FILE_CONTRACT.md"
  },
  "file": {
    "name": "filename.ext",
    "size": 12345678,
    "type": "video/mp4",
    "hash": "sha256_hash_of_file"
  },
  "ipfs": {
    "cid": "Qm...",
    "url": "/ipfs/Qm.../filename.ext",
    "gateway": "http://127.0.0.1:8080",
    "date": "2025-11-14T12:34:56Z",
    "node_id": "IPFSNODEID"
  },
  "metadata": {
    "description": "File description",
    "type": "video|audio|image|document|other",
    "title": "Human-readable title"
  },
  "nostr": {
    "nip94_tags": [
      ["url", "/ipfs/Qm.../filename.ext"],
      ["x", "sha256_hash"],
      ["m", "video/mp4"],
      ["size", "12345678"]
    ]
  }
}
```

## Format Variations by Media Type and Source

### 1. Video - Webcam/Personal Video (`webcam.html`, `ajouter_media.sh video`)

**Source**: User uploads via webcam interface or personal video file\
**Entry Point**: `webcam.html` → `/api/fileupload` → `upload2ipfs.sh`

```json
{
  "protocol": { ... },
  "file": { ... },
  "ipfs": { ... },
  "media": {
    "type": "video",
    "duration": 30.5,
    "dimensions": {
      "width": 1920,
      "height": 1080,
      "aspectRatio": "16:9"
    },
    "codecs": {
      "video": "h264",
      "audio": "aac"
    },
    "bitrate": {
      "video": 2500000,
      "audio": 128000
    },
    "frameRate": 30,
    "thumbnails": {
      "static": "QmThumbnailCID",
      "animated": "QmGifanimCID"
    }
  },
  "metadata": {
    "description": "Personal video recording",
    "type": "video",
    "title": "My Video"
  },
  "nostr": { ... }
}
```

**Key Features**:

* Standardized `media.type` field
* Nested `dimensions` object with width/height/aspect
* Nested `codecs` object
* Nested `thumbnails` object with `static` and `animated`
* No `source` section (personal upload)

***

### 2. Video - Film (`ajouter_media.sh film`)

**Source**: Film file with TMDB metadata\
**Entry Point**: `ajouter_media.sh film` → `upload2ipfs.sh --metadata "$TMDB_METADATA_FILE"`

```json
{
  "protocol": { ... },
  "file": { ... },
  "ipfs": { ... },
  "media": {
    "type": "video",
    "duration": 7200.0,
    "dimensions": {
      "width": 1920,
      "height": 1080,
      "aspectRatio": "16:9"
    },
    "codecs": {
      "video": "h264",
      "audio": "aac"
    },
    "bitrate": {
      "video": 2500000,
      "audio": 128000
    },
    "frameRate": 24,
    "thumbnails": {
      "static": "QmThumbnailCID",
      "animated": "QmGifanimCID"
    }
  },
  "source": {
    "type": "tmdb",
    "tmdb": {
      "id": 301528,
      "mediaType": "movie",
      "title": "Toy Story 4",
      "year": 2019,
      "url": "https://www.themoviedb.org/movie/301528-toy-story-4",
      "genres": ["Animation", "Adventure", "Comedy", "Family"],
      "director": "Josh Cooley",
      "runtime": 100,
      "voteAverage": 7.6,
      "voteCount": 1234,
      "tagline": "A new adventure begins.",
      "overview": "Woody has always been confident...",
      "productionCompanies": [...],
      "countries": [...],
      "languages": [...],
      "certification": "G",
      "posterPath": "/w9kR8qbmQ01HwnvK4alvnQ2ca0L.jpg",
      "backdropPath": "/yxZ0G9L6wRzKLW8WJ7G1TkNJ6nq.jpg"
    }
  },
  "metadata": {
    "description": "Woody has always been confident...",
    "type": "video",
    "title": "Toy Story 4 (2019)"
  },
  "nostr": { ... }
}
```

**Key Features**:

* Standardized `media` section (same as webcam)
* NEW `source` section with `type: "tmdb"`
* Consistent TMDB field naming (camelCase)
* Year as integer (not string)

***

### 3. Video - Serie (`ajouter_media.sh serie`)

**Source**: Episode file with TMDB metadata\
**Entry Point**: `ajouter_media.sh serie` → `upload2ipfs.sh --metadata "$TMDB_METADATA_FILE"`

```json
{
  "protocol": { ... },
  "file": { ... },
  "ipfs": { ... },
  "media": {
    "type": "video",
    "duration": 2400.0,
    "dimensions": {
      "width": 1920,
      "height": 1080,
      "aspectRatio": "16:9"
    },
    "codecs": {
      "video": "h264",
      "audio": "aac"
    },
    "bitrate": {
      "video": 2500000,
      "audio": 128000
    },
    "frameRate": 24,
    "thumbnails": {
      "static": "QmThumbnailCID",
      "animated": "QmGifanimCID"
    }
  },
  "source": {
    "type": "tmdb",
    "tmdb": {
      "id": 1396,
      "mediaType": "tv",
      "title": "Breaking Bad",
      "year": 2008,
      "url": "https://www.themoviedb.org/tv/1396-breaking-bad",
      "seriesName": "Breaking Bad",
      "episodeName": "Pilot",
      "seasonNumber": 1,
      "episodeNumber": 1,
      "genres": ["Crime", "Drama", "Thriller"],
      "creator": "Vince Gilligan",
      "network": "AMC",
      "status": "Ended",
      "numberOfSeasons": 5,
      "numberOfEpisodes": 62,
      "runtime": 49,
      "voteAverage": 9.5,
      "voteCount": 5678,
      "overview": "A high school chemistry teacher...",
      "posterPath": "/ggFHVNu6YYI5L9pCfOacjizRGt.jpg",
      "backdropPath": "/tsRy63Mu5cu8etL1X7ZLyf7UP1M.jpg"
    }
  },
  "metadata": {
    "description": "Breaking Bad S01E01 - Pilot",
    "type": "video",
    "title": "Breaking Bad - S01E01 - Pilot"
  },
  "nostr": { ... }
}
```

**Key Features**:

* Same `media` structure as webcam/film
* `source.type: "tmdb"` with `mediaType: "tv"`
* Episode-specific fields: `seriesName`, `episodeName`, `seasonNumber`, `episodeNumber`
* Consistent field naming (camelCase)

***

### 4. Video - YouTube (`ajouter_media.sh youtube`)

**Source**: YouTube video downloaded via `process_youtube.sh`\
**Entry Point**: `ajouter_media.sh youtube` → `process_youtube.sh` → `/api/fileupload` (with YouTube metadata)

```json
{
  "protocol": { ... },
  "file": { ... },
  "ipfs": { ... },
  "media": {
    "type": "video",
    "duration": 3600.0,
    "dimensions": {
      "width": 1280,
      "height": 720,
      "aspectRatio": "16:9"
    },
    "codecs": {
      "video": "h264",
      "audio": "aac"
    },
    "bitrate": {
      "video": 2628000,
      "audio": 128000
    },
    "frameRate": 30,
    "thumbnails": {
      "static": "QmThumbnailCID",
      "animated": "QmGifanimCID"
    }
  },
  "source": {
    "type": "youtube",
    "youtube": {
      "id": "dQw4w9WgXcQ",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "shortUrl": "https://youtu.be/dQw4w9WgXcQ",
      "title": "Video Title",
      "description": "Video description...",
      "uploader": "Channel Name",
      "uploaderId": "UC...",
      "uploaderUrl": "https://www.youtube.com/channel/UC...",
      "channel": {
        "name": "Channel Name",
        "id": "UC...",
        "url": "https://www.youtube.com/channel/UC...",
        "followerCount": 1234567
      },
      "stats": {
        "viewCount": 9876543,
        "likeCount": 123456,
        "commentCount": 5432,
        "averageRating": 4.8
      },
      "uploadDate": "2024-01-01",
      "releaseDate": "2024-01-01",
      "timestamp": 1704067200,
      "ageLimit": 0,
      "availability": "public",
      "liveStatus": "not_live",
      "wasLive": false,
      "categories": ["Entertainment", "Music"],
      "tags": ["music", "video", "entertainment"],
      "language": "en",
      "languages": ["en"],
      "location": "US",
      "license": "youtube",
      "format": {
        "id": "22",
        "note": "720p",
        "ext": "mp4"
      },
      "chapters": [...],
      "subtitles": {...},
      "automaticCaptions": {...},
      "thumbnailUrl": "https://i.ytimg.com/vi/.../maxresdefault.jpg"
    }
  },
  "metadata": {
    "description": "Video description...",
    "type": "video",
    "title": "Video Title"
  },
  "nostr": { ... }
}
```

**Key Features**:

* **BREAKING**: YouTube metadata now in `source.youtube` (NOT at root level)
* Consistent field naming (camelCase)
* Nested `channel` object
* Nested `stats` object
* Nested `format` object
* All yt-dlp metadata preserved but organized

***

### 5. Audio - MP3 (`ajouter_media.sh mp3`)

**Source**: MP3 file from YouTube or direct upload\
**Entry Point**: `ajouter_media.sh mp3` → `process_youtube.sh` (if YouTube) → `/api/fileupload`

```json
{
  "protocol": { ... },
  "file": {
    "name": "song.mp3",
    "size": 5242880,
    "type": "audio/mpeg",
    "hash": "sha256_hash"
  },
  "ipfs": { ... },
  "media": {
    "type": "audio",
    "duration": 180.5,
    "codecs": {
      "audio": "mp3"
    },
    "bitrate": {
      "audio": 320000
    },
    "sampleRate": 44100,
    "channels": 2
  },
  "source": {
    "type": "youtube",
    "youtube": {
      "id": "dQw4w9WgXcQ",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "title": "Song Title",
      "uploader": "Artist Name",
      "channel": {
        "name": "Channel Name",
        "id": "UC...",
        "url": "https://www.youtube.com/channel/UC..."
      },
      "stats": {
        "viewCount": 123456,
        "likeCount": 5432
      },
      "artist": "Artist Name",
      "album": "Album Name",
      "track": "Track Name",
      "thumbnailUrl": "https://i.ytimg.com/vi/.../maxresdefault.jpg"
    }
  },
  "metadata": {
    "description": "Song Title by Artist Name",
    "type": "audio",
    "title": "Song Title"
  },
  "nostr": { ... }
}
```

**Key Features**:

* `media.type: "audio"` with audio-specific fields
* No `thumbnails` section (not applicable to audio)
* YouTube metadata in `source.youtube` if from YouTube
* Consistent structure with video formats

***

### 6. Image (`/api/fileupload`)

**Source**: Image file upload\
**Entry Point**: `/api/fileupload` → `upload2ipfs.sh`

```json
{
  "protocol": { ... },
  "file": {
    "name": "image.jpg",
    "size": 1048576,
    "type": "image/jpeg",
    "hash": "sha256_hash"
  },
  "ipfs": { ... },
  "image": {
    "type": "image",
    "dimensions": {
      "width": 1920,
      "height": 1080,
      "aspectRatio": "16:9"
    },
    "format": "jpeg",
    "colorSpace": "sRGB",
    "exif": {
      "camera": "Canon EOS 5D",
      "lens": "24-70mm",
      "iso": 400,
      "aperture": "f/2.8",
      "shutterSpeed": "1/125",
      "focalLength": "50mm",
      "dateTaken": "2025-11-14T12:34:56Z",
      "location": {
        "latitude": 48.8566,
        "longitude": 2.3522
      }
    }
  },
  "metadata": {
    "description": "Image",
    "type": "image",
    "title": "My Photo"
  },
  "nostr": { ... }
}
```

**Key Features**:

* `image` section instead of `media`
* Standardized `dimensions` object
* EXIF metadata with nested `location`
* GPS data may be stripped for privacy

***

### 7. Document/PDF (`ajouter_media.sh pdf`)

**Source**: PDF file upload\
**Entry Point**: `ajouter_media.sh pdf` → `/api/fileupload` → `upload2ipfs.sh`

```json
{
  "protocol": { ... },
  "file": {
    "name": "document.pdf",
    "size": 2097152,
    "type": "application/pdf",
    "hash": "sha256_hash"
  },
  "ipfs": { ... },
  "metadata": {
    "description": "PDF document",
    "type": "document",
    "title": "My Document"
  },
  "nostr": { ... }
}
```

**Key Features**:

* No `media`, `image`, or `source` sections
* Minimal structure for non-media files

***

### 8. Re-upload (Provenance Tracking)

**Source**: Any file that was previously uploaded (detected by hash)\
**Entry Point**: Any upload → `upload2ipfs.sh` (provenance tracking)

```json
{
  "protocol": { ... },
  "file": { ... },
  "ipfs": { ... },
  "media": { ... },
  "source": { ... },
  "provenance": {
    "originalEventId": "abc123...",
    "originalAuthor": "63fe6318dc...",
    "uploadChain": [
      {
        "pubkey": "original_pubkey",
        "timestamp": null
      },
      {
        "pubkey": "second_pubkey",
        "timestamp": "2025-11-14T10:00:00Z"
      },
      {
        "pubkey": "current_pubkey",
        "timestamp": "2025-11-14T12:00:00Z"
      }
    ],
    "isReupload": true
  },
  "metadata": { ... },
  "nostr": { ... }
}
```

**Key Features**:

* `provenance` section with camelCase field names
* `uploadChain` as array with timestamp objects
* New info.json created on each re-upload
* Main file CID is reused

***

## Field Name Standardization

### General Rules

1. **camelCase** for all field names (NOT snake\_case)
2. **Dates**: ISO 8601 format `YYYY-MM-DDTHH:mm:ssZ`
3. **Numbers**: Always numeric types (not strings)
4. **URLs**: Always include protocol (`https://`)
5. **Nested objects**: Use nested structures for related data

### Common Field Mappings (v1.0 → v2.0)

| v1.0 (snake\_case)    | v2.0 (camelCase)      | Section          |
| --------------------- | --------------------- | ---------------- |
| `video_codecs`        | `codecs.video`        | `media`          |
| `audio_codecs`        | `codecs.audio`        | `media`          |
| `thumbnail_ipfs`      | `thumbnails.static`   | `media`          |
| `gifanim_ipfs`        | `thumbnails.animated` | `media`          |
| `dimensions` (string) | `dimensions` (object) | `media`/`image`  |
| `tmdb_id`             | `id`                  | `source.tmdb`    |
| `media_type`          | `mediaType`           | `source.tmdb`    |
| `series_name`         | `seriesName`          | `source.tmdb`    |
| `episode_name`        | `episodeName`         | `source.tmdb`    |
| `season_number`       | `seasonNumber`        | `source.tmdb`    |
| `episode_number`      | `episodeNumber`       | `source.tmdb`    |
| `youtube_id`          | `id`                  | `source.youtube` |
| `channel_id`          | `channel.id`          | `source.youtube` |
| `view_count`          | `stats.viewCount`     | `source.youtube` |
| `like_count`          | `stats.likeCount`     | `source.youtube` |
| `upload_date`         | `uploadDate`          | `source.youtube` |
| `upload_chain`        | `uploadChain`         | `provenance`     |
| `original_author`     | `originalAuthor`      | `provenance`     |

***

## Summary Table

| Section      | Video | Audio | Image | PDF | When Present            |
| ------------ | ----- | ----- | ----- | --- | ----------------------- |
| `protocol`   | ✅     | ✅     | ✅     | ✅   | Always                  |
| `file`       | ✅     | ✅     | ✅     | ✅   | Always                  |
| `ipfs`       | ✅     | ✅     | ✅     | ✅   | Always                  |
| `media`      | ✅     | ✅     | ❌     | ❌   | Video/Audio only        |
| `image`      | ❌     | ❌     | ✅     | ❌   | Image only              |
| `source`     | ✅\*   | ✅\*   | ❌     | ❌   | If from external source |
| `provenance` | ✅\*   | ✅\*   | ✅\*   | ✅\* | Re-uploads only         |
| `metadata`   | ✅     | ✅     | ✅     | ✅   | Always                  |
| `nostr`      | ✅     | ✅     | ✅     | ✅   | Always                  |

\*Conditional: Only present if applicable

***

## Migration Notes

### Breaking Changes from v1.0

1. **YouTube metadata location**:
   * v1.0: At root level
   * v2.0: In `source.youtube` section
2. **TMDB metadata location**:
   * v1.0: In `tmdb` section at root
   * v2.0: In `source.tmdb` section
3. **Field naming**:
   * v1.0: snake\_case (`video_codecs`, `thumbnail_ipfs`)
   * v2.0: camelCase + nested objects (`codecs.video`, `thumbnails.static`)
4. **Dimensions format**:
   * v1.0: String `"1920x1080"`
   * v2.0: Object `{"width": 1920, "height": 1080, "aspectRatio": "16:9"}`
5. **Date format**:
   * v1.0: Various formats (`"2025-01-01 12:00 +0000"`, `"20250101"`)
   * v2.0: ISO 8601 `"2025-11-14T12:34:56Z"`

### Detection

Use `protocol.version` to detect format version:

* v1.0: `"version": "1.0.0"`
* v2.0: `"version": "2.0.0"`

### Cleanup

Use `TUBE.manager.sh cleanup` to identify and optionally delete v1.0 events.

***

## Canonicalization

All `info.json` files are canonicalized according to **RFC 8785 (JCS)** before IPFS upload for deterministic CID generation.
