Module: X::Uploader::Metadata

Extended by:

Metadata

Included in:

Metadata

Defined in:

x-uploader/lib/x/uploader/metadata.rb

Overview

Describes uploaded media with alt text, and uploaded videos with subtitles

Class Method Summary

• .add_alt_text(media, text, client:) ⇒ UploadedMedia

  Describe uploaded media with alt text, for people who cannot see it.

• .add_subtitles(video, subtitles, language_code, client:, display_name: nil, media_category: SUBTITLED_MEDIA_CATEGORY) ⇒ UploadedMedia

  Attach uploaded subtitles to an uploaded video.

Instance Method Summary

• #add_alt_text(media, text, client:) ⇒ UploadedMedia

  Describe uploaded media with alt text, for people who cannot see it.

• #add_subtitles(video, subtitles, language_code, client:, display_name: nil, media_category: SUBTITLED_MEDIA_CATEGORY) ⇒ UploadedMedia

  Attach uploaded subtitles to an uploaded video.

Class Method Details

.add_alt_text(media, text, client:) ⇒ UploadedMedia

Describe uploaded media with alt text, for people who cannot see it

Alt text added twice is added once, so it is sent again after a server or network error, as a client sends an idempotent request again, up to the max_retries of the client.

It returns the media it described, as uploaded media, so that a call can be chained to the upload it describes. The response holds nothing more than the media identifier and the alt text that was sent.

Examples:

Describe an uploaded image

Uploader::Metadata.add_alt_text(media, "A cat asleep on a keyboard", client: client)

Describe an image as it is uploaded, and attach it to a post

media = Uploader::Metadata.add_alt_text(Uploader::MediaUpload.upload("cat.jpg", client:), "A cat", client:)
client.post("tweets", {text: "Look at this cat", media: {media_ids: [media.media_id.to_s]}})

Parameters:

• media (UploadedMedia, Hash, #media_key, String, Integer) —

  the uploaded media, media that has a media key, such as X::Media, the media key, or the media identifier

• text (String) —

  the alt text, of 1 to 1,000 characters

• client (Client) —

  the X API client

Returns:

• (UploadedMedia) —

  the media given, if it is uploaded media, or else uploaded media built from the upload response, the media key, or the media identifier given

Raises:

• (ArgumentError) —

  if the alt text is empty or longer than the API takes, before a request

• (ArgumentError) —

  if the media given is nil, holds no identifier, or is neither media, a media key, nor a media identifier, or its media key names none

• (MissingMediaData) —

  if the response holds no metadata or carries no body at all

# File 'x-uploader/lib/x/uploader/metadata.rb', line 44

def add_alt_text(media, text, client:)
  Validator.validate_alt_text!(text)
  body = {id: Utils.media_id(media), metadata: {alt_text: {text:}}}
  Utils.described(Utils.sending_again(client) { client.post("media/metadata", body, **JSON_CLASSES) }, media)
end

.add_subtitles(video, subtitles, language_code, client:, display_name: nil, media_category: SUBTITLED_MEDIA_CATEGORY) ⇒ UploadedMedia

Attach uploaded subtitles to an uploaded video

Subtitles attached twice are attached once, as the track of their language, so they are sent again after a server or network error, as alt text is, up to the max_retries of the client.

It returns the video it subtitled, as uploaded media, so that a call can be chained to the upload of the video. The response holds nothing more than the identifiers, the category, and the track that were sent.

Examples:

Upload a video and its English subtitles

video = Uploader::MediaUpload.upload("cat.mp4", client: client)
subtitles = Uploader::MediaUpload.upload("cat.srt", client: client)
Uploader::Metadata.add_subtitles(video, subtitles, "EN", client: client, display_name: "English")

Subtitle an Amplify video

video = Uploader::MediaUpload.upload("cat.mp4", client: client, media_category: :amplify_video)
Uploader::Metadata.add_subtitles(video, subtitles, "EN", client: client, media_category: :amplify_video)

Parameters:

• video (UploadedMedia, Hash, #media_key, String, Integer) —

  the uploaded video, media that has a media key, such as X::Media, or its media identifier

• subtitles (UploadedMedia, Hash, #media_key, String, Integer) —

  the uploaded .srt file, media that has a media key, or its media identifier

• language_code (String) —

  the two-letter language code of the subtitles, in any case, such as EN

• client (Client) —

  the X API client

• display_name (String, nil) (defaults to: nil) —

  the name of the language shown to viewers, such as English

• media_category (String, Symbol) (defaults to: SUBTITLED_MEDIA_CATEGORY) —

  the category the video was uploaded as, tweet_video, the default, or amplify_video, in any case, as the uploaders take it, or as the subtitles endpoint names it, TweetVideo or AmplifyVideo

Returns:

• (UploadedMedia) —

  the video given, if it is uploaded media, or else uploaded media built from the upload response, the media key, or the media identifier given

Raises:

• (ArgumentError) —

  if the media category is neither tweet_video nor amplify_video, or the language code is not two letters

• (ArgumentError) —

  if the video or the subtitles are nil, hold no identifier, are neither media, a media key, nor a media identifier, have a media key that names none, or an identifier the API does not take

• (MissingMediaData) —

  if the response holds no metadata or carries no body at all

# File 'x-uploader/lib/x/uploader/metadata.rb', line 83

def add_subtitles(video, subtitles, language_code, client:, display_name: nil, media_category: SUBTITLED_MEDIA_CATEGORY)
  track = {id: Utils.media_id(subtitles), language_code: Validator.validate_language_code!(language_code), display_name:}.compact
  body = {id: Utils.media_id(video), media_category: Utils.subtitled_media_category(media_category), subtitles: track}
  Utils.described(Utils.sending_again(client) { client.post("media/subtitles", body, **JSON_CLASSES) }, video)
end

Instance Method Details

#add_alt_text(media, text, client:) ⇒ UploadedMedia

Describe uploaded media with alt text, for people who cannot see it

Alt text added twice is added once, so it is sent again after a server or network error, as a client sends an idempotent request again, up to the max_retries of the client.

It returns the media it described, as uploaded media, so that a call can be chained to the upload it describes. The response holds nothing more than the media identifier and the alt text that was sent.

Examples:

Describe an uploaded image

Uploader::Metadata.add_alt_text(media, "A cat asleep on a keyboard", client: client)

Describe an image as it is uploaded, and attach it to a post

media = Uploader::Metadata.add_alt_text(Uploader::MediaUpload.upload("cat.jpg", client:), "A cat", client:)
client.post("tweets", {text: "Look at this cat", media: {media_ids: [media.media_id.to_s]}})

Parameters:

• media (UploadedMedia, Hash, #media_key, String, Integer) —

  the uploaded media, media that has a media key, such as X::Media, the media key, or the media identifier

• text (String) —

  the alt text, of 1 to 1,000 characters

• client (Client) —

  the X API client

Returns:

• (UploadedMedia) —

  the media given, if it is uploaded media, or else uploaded media built from the upload response, the media key, or the media identifier given

Raises:

• (ArgumentError) —

  if the alt text is empty or longer than the API takes, before a request

• (ArgumentError) —

  if the media given is nil, holds no identifier, or is neither media, a media key, nor a media identifier, or its media key names none

• (MissingMediaData) —

  if the response holds no metadata or carries no body at all

# File 'x-uploader/lib/x/uploader/metadata.rb', line 44

def add_alt_text(media, text, client:)
  Validator.validate_alt_text!(text)
  body = {id: Utils.media_id(media), metadata: {alt_text: {text:}}}
  Utils.described(Utils.sending_again(client) { client.post("media/metadata", body, **JSON_CLASSES) }, media)
end

#add_subtitles(video, subtitles, language_code, client:, display_name: nil, media_category: SUBTITLED_MEDIA_CATEGORY) ⇒ UploadedMedia

Attach uploaded subtitles to an uploaded video

Subtitles attached twice are attached once, as the track of their language, so they are sent again after a server or network error, as alt text is, up to the max_retries of the client.

It returns the video it subtitled, as uploaded media, so that a call can be chained to the upload of the video. The response holds nothing more than the identifiers, the category, and the track that were sent.

Examples:

Upload a video and its English subtitles

video = Uploader::MediaUpload.upload("cat.mp4", client: client)
subtitles = Uploader::MediaUpload.upload("cat.srt", client: client)
Uploader::Metadata.add_subtitles(video, subtitles, "EN", client: client, display_name: "English")

Subtitle an Amplify video

video = Uploader::MediaUpload.upload("cat.mp4", client: client, media_category: :amplify_video)
Uploader::Metadata.add_subtitles(video, subtitles, "EN", client: client, media_category: :amplify_video)

Parameters:

• video (UploadedMedia, Hash, #media_key, String, Integer) —

  the uploaded video, media that has a media key, such as X::Media, or its media identifier

• subtitles (UploadedMedia, Hash, #media_key, String, Integer) —

  the uploaded .srt file, media that has a media key, or its media identifier

• language_code (String) —

  the two-letter language code of the subtitles, in any case, such as EN

• client (Client) —

  the X API client

• display_name (String, nil) (defaults to: nil) —

  the name of the language shown to viewers, such as English

• media_category (String, Symbol) (defaults to: SUBTITLED_MEDIA_CATEGORY) —

  the category the video was uploaded as, tweet_video, the default, or amplify_video, in any case, as the uploaders take it, or as the subtitles endpoint names it, TweetVideo or AmplifyVideo

Returns:

• (UploadedMedia) —

  the video given, if it is uploaded media, or else uploaded media built from the upload response, the media key, or the media identifier given

Raises:

• (ArgumentError) —

  if the media category is neither tweet_video nor amplify_video, or the language code is not two letters

• (ArgumentError) —

  if the video or the subtitles are nil, hold no identifier, are neither media, a media key, nor a media identifier, have a media key that names none, or an identifier the API does not take

• (MissingMediaData) —

  if the response holds no metadata or carries no body at all

# File 'x-uploader/lib/x/uploader/metadata.rb', line 83

def add_subtitles(video, subtitles, language_code, client:, display_name: nil, media_category: SUBTITLED_MEDIA_CATEGORY)
  track = {id: Utils.media_id(subtitles), language_code: Validator.validate_language_code!(language_code), display_name:}.compact
  body = {id: Utils.media_id(video), media_category: Utils.subtitled_media_category(media_category), subtitles: track}
  Utils.described(Utils.sending_again(client) { client.post("media/subtitles", body, **JSON_CLASSES) }, video)
end