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.

Signature:

async getAllFolders(): Promise<MediaFolder[]>

Returns: Promise<MediaFolder[]> - Array of folder objects

MediaFolder Type:

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

Example:

const folders = 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
  contentFolderId: string;       // Parent folder ID
  contentType: string;           // MIME type (image/jpeg, video/mp4, etc.)
  name: string;                  // Media name
  description: string;           // Media description
  thumbnailUrl: string;          // Thumbnail URL
  keys: string[];                // Associated keys/tags
  publicUrls: string[];          // CDN URLs for accessing content
  hidden: boolean;               // Visibility flag
  validFrom?: Date;              // Optional start date
  validTo?: Date;                // Optional end date
  transcodedAt?: Date;           // Video transcoding timestamp
  createdAt: Date;               // Upload timestamp
  updatedAt: Date;               // Last modification
}

Key Fields:

publicUrls - Array of CDN URLs (use first element)
contentType - MIME type for rendering
keys - Tags for filtering/searching

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