Handling Thumbnails

All thumbnails (excluding Youtube videos) are stored in Google’s Cloud Storage. However, Album thumbnails are handled differently than MediaItem thumbnails. Since there is currently no method to support adding an Album to a MediaItem, Album thumbnails are currently uploaded directly via the Cloud Storage console. Thumbnails can only be displayed using a specific download URL, which cannot be obtained from the console. The only method is to call getDownloadURL() with the path to that specific uploaded file name (including the file extension), which requires the file name to be stored in the database under the thumbnail field of Albums. Note that files cannot be renamed once uploaded to Cloud Storage.

For MediaItems, there are two different types of thumbnails in Media Hub: Static (png, jpg, gifs, etc) and Video (Youtube Video). Images and interactives have static thumbnails, whereas videos and animations have video-type thumbnails. Although each MediaItem has a different thumbnail type, the main search page will display them as static. Youtube thumbnails can be played when the user clicks on an item to preview.

Different thumbnail types have different storage and retrieval methods. Cloud Storage is only used for storing the static thumbnails, and their download urls are saved to Firestore for rendering as an image. For a Youtube Video, only the Youtube ID gets saved to Firestore for easier embedding.

In Cloud Storage, Album thumbnails are stored in a folder called album_thumbnails, whereas MediaItem thumbnails are stored in a folder called images.

Static Thumbnails (Cloud Storage)

Static thumbnails are stored in Cloud Storage. Due to account limitations and performance considerations, user-uploaded thumbnails must be limited to some small size, preferably less than 500kB. All thumbnails are stored in an images folder, and are titled after the Box Folder ID.

Uploading a File

Files are uploaded to Cloud Storage by first creating a reference to the full path of the file and then calling uploadBytes() to upload files from the File or Blob API.

// Assuming all configurations have been setup

// Reference to where file should be stored, including the file name (ie. Box ID)
const pathRef = ref(getStorage(), `images/${mediaId.value.trim()}`);

// Upload files from File/Blob API
await uploadBytes(pathRef, thumbnail).then( (snapshot) => {
  console.log('Uploaded a blob!')
});

Downloading a File

For the purposes of Media Hub, thumbnails are not directly downloaded onto the user’s local machine. Instead, the download url of the file must be retrieved, which contains a unique access token. Download urls are retrieved using getDownloadUrl() and are of the form https://firebasestorage.googleapis.com/v0/b/{{ BUCKET }}/o/{{ PATH }}?alt=media&token={{ SPECIAL TOKEN }}. This download url is then stored in the thumbnail field in Firestore.

const thumbnailLink = await getDownloadURL(pathRef).then( (url) => {
  return url;
});

Display Rendering

As the download urls are saved to Firestore, the images can be simply displayed by passing the url into the src attribute of an <img> tag.

Video Thumbnails (Youtube)

When uploading a Youtube thumbnail, the user is prompted for the shareable link that is given in the form https://youtu.be/{{ ID }}. Once the ID is extracted from the link, it can be used to display the static frame (for the search results) and embed the video (for previewing).

• Embedding an iFrame: https://www.youtube.com/embed/${youtubeId}

• Retrieving the static frame: https://img.youtube.com/vi/${youtubeId}/{size}.jpg where size refers to the following thumbnail size options (sourced from YouTube Image Thumbnail URLs ):

Parameter	Actual Size (px)
0	480 x 360
1 (screen cap at different time)	120 x 90
2 (screen cap at different time)	120 x 90
3 (screen cap at different time)	120 x 90
default	120 x 90
mqdefault	320 x 180
hqdefault	480 x 360
sddefault	640 x 480
maxresdeault	Matches resolution of video

maxresdefault and mqdefault are the only sizes that provide a thumbnail without the black borders. maxresdefault will automatically fill in the space in the masonry grid whereas mqdefault does not; however, maxresdefault does not show a thumbnail if the video is considered to be low quality. Thus, mqdefault is the most suitable and reliable option.