Media Methods

Access TelemetryOS media library content.

Overview

The Media Methods provide access to media content (images, videos) uploaded to the TelemetryOS platform. Applications can query folders, retrieve content by tags, access media URLs for display, and open an interactive media picker for user selection.

Importing

import { media } from '@telemetryos/sdk';

Methods

getAllFolders()

Retrieve all media folders in the account, as both a flat list and a hierarchical tree.

Signature:

async getAllFolders(): Promise<{ folders: MediaFolder[]; foldersTree: MediaFolderTreeNode[] }>

Returns: Promise<{ folders, foldersTree }> - Flat list of folders and a nested tree

MediaFolder Type:

type MediaFolder = {
  id: string;
  parentId: string;
  name: string;
  size: number;
  default: boolean;
  updatedAt: Date;
  createdAt: Date;
}

MediaFolderTreeNode Type:

type MediaFolderTreeNode = MediaFolder & {
  nodes: MediaFolderTreeNode[];
}

Example:

const { folders, foldersTree } = await media().getAllFolders();

getAllByFolderId()

Retrieve all media content within a specific folder.

Signature:

async getAllByFolderId(folderId: string): Promise<MediaContent[]>

Parameters:

folderId - Folder ID to query

Returns: Promise<MediaContent[]> - Array of media content

Example:

const contents = await media().getAllByFolderId('folder-123');

getAllByTag()

Retrieve media content tagged with a specific tag.

Signature:

async getAllByTag(tagName: string): Promise<MediaContent[]>

Parameters:

tagName - Tag name to filter by

Returns: Promise<MediaContent[]> - Array of media content

Example:

const marketingContent = await media().getAllByTag('marketing');

getById()

Retrieve a specific media item by its ID.

Signature:

async getById(id: string): Promise<MediaContent>

Parameters:

id - Media content ID

Returns: Promise<MediaContent> - Media content object

Example:

const item = await media().getById('media-456');

openPicker()

Opens a full-screen media picker dialog in the host window. Users can browse folders, view media, and select an item.

Signature:

async openPicker(options?: MediaPickerOptions): Promise<MediaSelection | null>

Parameters:

options (optional) - Picker configuration
- accept - Array of content type patterns to filter by (e.g. ['image/*'], ['video/*'])
- currentValue - A MediaSelection to pre-select in the picker

Returns: Promise<MediaSelection | null> - The selected media, or null if the user cancels

Example:

// Open picker with all media types
const selection = await media().openPicker();
if (selection) {
  console.log(selection.url);
}

// Open picker filtered to images only
const image = await media().openPicker({
  accept: ['image/*'],
});

Types

MediaContent

type MediaContent = {
  id: string;                    // Unique media ID
  folderId: string;              // Parent folder ID
  contentType: string;           // MIME type (image/jpeg, video/mp4, etc.)
  name: string;                  // Media name
  description?: string;          // Media description
  thumbUrl: string;              // Thumbnail URL
  publicUrl: string;             // CDN URL for display
  publicUrls?: string[];         // Additional format URLs (when present)
  tags?: string[];               // User-applied tags
  size?: number;                 // Size in bytes
  width?: number;                // Image/video width
  height?: number;               // Image/video height
  length?: number;               // Video duration in seconds
  createdAt: Date;               // Upload timestamp
  updatedAt: Date;               // Last modification
  createdBy: {
    id: string;
    name: string;
    email: string;
    imageUrl?: string;
  };
  isTranscoded?: boolean;        // Video has been transcoded
  transcodedAt?: Date;           // Video transcoding timestamp
  videoEncoding?: string;        // e.g. 'H.264', 'VP9'
  subtitles?: {
    contentId: string;
    name: string;
    url: string;
  };
}

Key Fields:

publicUrl - Primary CDN URL for display
contentType - MIME type for rendering
tags - User-applied tags for filtering/searching (use getAllByTag() to query)
length - Video duration in seconds
width / height - Image or video dimensions

MediaSelection

Represents a selected media item returned by openPicker().

type MediaSelection = {
  id: string;            // Unique media ID
  name: string;          // Media name
  thumbnailUrl: string;  // Thumbnail URL
  url: string;           // Full content URL
  contentType: string;   // MIME type
}

MediaPickerOptions

Options for configuring the media picker dialog.

type MediaPickerOptions = {
  accept?: string[];            // Content type filter patterns (e.g. ['image/*', 'video/*'])
  currentValue?: MediaSelection; // Pre-select the current value in the picker
}

React Components

SettingsMediaSelect

A ready-made media selection component for Settings views. Displays a thumbnail button that opens the media picker when clicked.

Import:

import { SettingsMediaSelect } from '@telemetryos/sdk/react';
import type { MediaSelection } from '@telemetryos/sdk/react';

Props:

Prop	Type	Default	Description
`value`	`MediaSelection \| null`	—	Currently selected media
`onChange`	`(selection: MediaSelection \| null) => void`	—	Called when selection changes or is cleared
`disabled`	`boolean`	`false`	Disable the picker
`placeholder`	`string`	`'Select media...'`	Tooltip when no media is selected
`accept`	`string[]`	—	Content type filter patterns

Example:

import { SettingsMediaSelect } from '@telemetryos/sdk/react';
import type { MediaSelection } from '@telemetryos/sdk/react';
import { useState } from 'react';

function MySettings() {
  const [image, setImage] = useState<MediaSelection | null>(null);

  return (
    <SettingsMediaSelect
      value={image}
      onChange={setImage}
      accept={['image/*']}
    />
  );
}

Next Steps

Storage API - Cache media references
Code Examples - Complete media gallery example
Platform APIs - Other integration APIs