joystream/metadata-protobuf/doc/index.md

Protocol Documentation

Table of Contents

• proto/Channel.proto

  • ChannelCategoryMetadata
  • ChannelMetadata
    

• proto/Person.proto

  • PersonMetadata
    

• proto/Playlist.proto

  • PlaylistMetadata
    

• proto/Series.proto

  • SeasonMetadata
  • SeriesMetadata
    

• proto/Storage.proto

  • DistributionBucketFamilyMetadata
  • DistributionBucketOperatorMetadata
  • GeoCoordiantes
  • GeographicalArea
  • NodeLocationMetadata

  • StorageBucketOperatorMetadata

  • GeographicalArea.Continent

• proto/Video.proto

  • License
  • MediaType
  • PublishedBeforeJoystream
  • VideoCategoryMetadata
  • VideoMetadata
    

• Scalar Value Types

Top

proto/Channel.proto

ChannelCategoryMetadata

Field	Type	Label	Description
name	string	optional	Category Name

ChannelMetadata

Field	Type	Label	Description
title	string	optional	Channel Title
description	string	optional	Channel Description
is_public	bool	optional	Wether to display channel to the public
language	string	optional	ISO_639-1 Language Code
cover_photo	uint32	optional	index into external assets array
avatar_photo	uint32	optional	index into external assets array
category	uint64	optional	Channel Category Id

Top

proto/Person.proto

PersonMetadata

Field	Type	Label	Description
first_name	string	optional
middle_name	string	optional
last_name	string	optional
about	string	optional
cover_photo	uint32	optional	index into external assets array
avatar_photo	uint32	optional	index into external assets array

Top

proto/Playlist.proto

PlaylistMetadata

Field	Type	Label	Description
title	string	optional
videos	uint64	repeated	Videos in the playlist

Top

proto/Series.proto

SeasonMetadata

Field	Type	Label	Description
title	string	optional
description	string	optional
cover_photo	uint32	optional	index into external assets array
persons	uint64	repeated	Person(s) referenced by PersonId involved in this Season

SeriesMetadata

Field	Type	Label	Description
title	string	optional
description	string	optional
cover_photo	uint32	optional	index into external assets array
persons	uint64	repeated	Person(s) referenced by PersonId involved in this Series

Top

proto/Storage.proto

DistributionBucketFamilyMetadata

Field	Type	Label	Description
region	string	optional	ID / name of the region covered by the distribution family (ie. us-east-1). Should be unique.
description	string	optional	Additional, more specific description of the region
areas	GeographicalArea	repeated	Standarized geographical areas covered by the family (providing [{}] will unset the current value)
latency_test_targets	string	repeated	List of targets (hosts/ips) best suited latency measurements for this family

DistributionBucketOperatorMetadata

Field	Type	Label	Description
endpoint	string	optional	Root distribution node endpoint (ie. https://example.com/distribution)
location	NodeLocationMetadata	optional	Information about node's phisical location (providing {} will unset current value)
extra	string	optional	Additional information about the node / node operator

GeoCoordiantes

Field	Type	Label	Description
latitude	float	optional
longitude	float	optional

GeographicalArea

Field	Type	Label	Description
continent	GeographicalArea.Continent	optional
country_code	string	optional	ISO 3166-1 alpha-2 country code
subdivision_code	string	optional	ISO 3166-2 subdivision code

NodeLocationMetadata

Field	Type	Label	Description
country_code	string	optional	ISO 3166-1 alpha-2 country code (2 letters)
city	string	optional	City name
coordinates	GeoCoordiantes	optional	Geographic coordinates (providing {} will unset current value)

StorageBucketOperatorMetadata

Field	Type	Label	Description
endpoint	string	optional	Root storage node endpoint (ie. https://example.com/storage)
location	NodeLocationMetadata	optional	Information about node's phisical location (providing {} will unset current value)
extra	string	optional	Additional information about the node / node operator

GeographicalArea.Continent

Name	Number	Description
AF	1
NA	2
OC	3
AN	4
AS	5
EU	6
SA	7

Top

proto/Video.proto

License

License types defined by Joystream

Field	Type	Label	Description
code	uint32	optional	License code defined by Joystream. reference
attribution	string	optional	Text for licenses that require an attribution
custom_text	string	optional	Text for custom license type

MediaType

Codec, Container, MIME media-type information

Field	Type	Label	Description
codec_name	string	optional	Codec corresponding to name field from FFmpeg
container	string	optional	Video container format, eg. 'MP4', 'WebM', 'Ogg' ref
mime_media_type	string	optional	MIME Media Type, eg. 'video/mp4' ref

PublishedBeforeJoystream

Publication status before joystream

Field	Type	Label	Description
is_published	bool	optional	Was video published before joystream platform
date	string	optional	Date of publication: 'YYYY-MM-DD' ISO-8601

VideoCategoryMetadata

Field	Type	Label	Description
name	string	optional	Category name

VideoMetadata

Field	Type	Label	Description
title	string	optional	Video Title
description	string	optional	Video Description
video	uint32	optional	index into external assets array
thumbnail_photo	uint32	optional	index into external assets array
duration	uint32	optional	Lengths of video in seconds
media_pixel_height	uint32	optional	Resolution of the video (Height)
media_pixel_width	uint32	optional	Resolution of the video (Width)
media_type	MediaType	optional	Encoding and Container format used
language	string	optional	ISO_639-1 Language Code
license	License	optional	License type for the media
published_before_joystream	PublishedBeforeJoystream	optional	Date of publication
has_marketing	bool	optional	Does video have marketing or advertising in the stream
is_public	bool	optional	Should video be publicy visible yet
is_explicit	bool	optional	Does Video have explicit language or scenes
persons	uint64	repeated	Person(s) referenced by PersonId involved in this video
category	uint64	optional	Video Category Id

Scalar Value Types

| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | | ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | | double | | double | double | float | float64 | double | float | Float | | float | | float | float | float | float32 | float | float | Float | | int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum | | uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | | uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | | sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | | bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |

Referencing Assets

Applications that process messages that contain a uint32 field that references an asset such as a cover photo or video, should interpret this value as a zero based index into an array/vector that is received external (out of band) to the protobuf message.

Example in context of query-node processing the runtime event VideoCreated

// Runtime event associated with creating a Video
VideoCreated(video_id: VideoId, video: Video, assets: Vec<NewAsset>, params: VideoCreationParameters)

struct VideoCreationParameters {
  in_category: VideoCategoryId,
  // binary serialized VideoMetadata protobuf message
  meta: Vec<u8>,
}

// suppose assets is a vector of two elements. This is the "out of band" array being referenced by the VideoMetadata message
assets = [
    NewAsset::Uri("https://mydomain.net/thumbnail.png"),
    NewAsset::Upload({
       content_id,
       ipfs_hash,
       size,
       ...
    }),
];

meta = VideoMetadata {
    ...
    // refers to second element: assets[1] which is being uploaded to the storage system
    video: 1,
    // refers to the first element assets[0] which is being referneced by a url string.
    thumbnail_photo: 0,
    ...
};