Guides
Login

Create and manage video playlists

Learn how to create, organize, and manage video playlists in FastPix with automatic filtering, API integration, and playback configuration for seamless video delivery.

This guide covers manual and smart playlists, adding media, reordering content, and controlling playback.

FastPix playlists help you organize and present multiple videos in a structured sequence. You can create two types of playlists:

  • Manual playlists: You select and arrange specific videos
  • Smart playlists: Videos are automatically included based on metadata filters

NOTE:
Both playlist types support up to 1,000 videos and can be managed through the FastPix dashboard or API.


What you'll learn

In this guide, you'll learn how to:

  • Create manual playlists to highlight specific video collections
  • Set up smart playlists that automatically populate based on date filters
  • Add, remove, and reorder videos in your playlists
  • Integrate playlists into your website with the FastPix player
  • Update playlist metadata and manage playback settings
  • Use the FastPix API to programmatically control playlists
  • Apply best practices for organizing video content at scale

Before you begin

Make sure you have:


Create manual playlists

Manual playlists give you complete control over which videos appear and in what order. Use manual playlists when you want to highlight specific content, such as featured videos, product showcases, or educational series.

Create a manual playlist in the dashboard

To create a manual playlist:

  1. Go to FastPix Dashboard > Products > Playlist.
  2. Click Create Playlist.
  3. Select Manual Playlist.
  4. Enter the playlist details:
    • Name: A descriptive title for your playlist
    • Reference ID: A unique identifier for your playlist. This ID must be unique within your workspace and helps you reference the playlist in your applications.
    • Description: Notes about the playlist's purpose or content to help you organize your media library.
  5. Click Create.
  6. Add videos to your playlist:
    • Navigate to your newly created playlist.
    • Click Add Media.
    • Enter one or more Media IDs (one per line for multiple videos).
    • Click Add Media to confirm.
  7. Drag videos to reorder them. Changes are saved automatically.

Create a manual playlist using the API

To create a manual playlist programmatically, send a POST request to the create playlist endpoint.

https://api.fastpix.io/v1/on-demand/playlists

Here’s an example of the request body for creating a manual playlist:

Request body:

{ 
  "name": "my playlist", 
  "referenceId": "new20", 
  "type": "manual", 
  "description": "This is a manual playlist" 
}

Parameters:

  • name (required): Display name for the playlist
  • referenceId (required): Unique identifier within your workspace
  • type (required): Set to "manual"
  • description (optional): Additional context about the playlist

Here's an example of the response body for creating a manual playlist:

{ 
  "name": "my playlist", 
  "referenceId": "new20", 
  "type": "manual", 
  "description": "This is a manual playlist" 
}

Create smart playlists

Smart playlists automatically include videos based on metadata criteria. Use smart playlists for time-based collections, such as "Videos from this month" or "Recent uploads."

Create a smart playlist in the dashboard

To create a smart playlist:

  1. Go to FastPix Dashboard > Products > Playlist.
  2. Click Create Playlist.
  3. Select Smart Playlist as the playlist type.
  4. Enter the basic details (Name, Reference ID, Description).
  5. Configure the playlist filters:
    • Play Order: Choose Newest First or Oldest First to display the most recently created videos at the top, or the earliest videos first
    • Created Date Range: Set start and end dates for filtering media
    • Updated Date Range: Filter by last modified date
    • Media Limit: Maximum number of videos to include. This caps the playlist size even if more videos match your filters.
  6. Click Create. The playlist automatically includes all media matching your filter criteria.

Create a smart playlist using the API

Send a POST request with metadata filters:

{
  "name": "my smart playlist",
  "referenceId": "JanuaryToJune",
  "type": "smart",
  "description": "This playlist contains videos created from January to june 2025",
  "playOrder": "createdDate ASC",
  "limit": 20,
  "metadata": {
    "createdDate": {
      "startDate": "2025-01-01",
      "endDate": "2025-06-06"
    }
  }
}

Parameters:

  • name (required): Display name for the playlist
  • referenceId (required): Unique identifier within your workspace
  • type (required): Set to "smart"
  • playOrder (optional): "createdDate ASC" or "createdDate DESC"
  • limit (optional): Maximum number of videos
  • metadata (required): Filter criteria with createdDate or updatedDate

Here’s an example of the response body for creating a smart playlist:

{
    "success": true,
    "data": {
        "id": "adad6a6d-6985-4ce9-ba9b-8ac0e08cdeb7",
        "name": "my smart playlist",
        "referenceId": "JanuaryToJune2",
        "type": "smart",
        "description": "This playlist contains videos created from January to june 2025",
        "playOrder": "createdDate ASC",
        "metadata": {
            "createdDate": {
                "endDate": "2025-10-17",
                "startDate": "2025-10-01"
            }
        },
        "mediaList": [
            {
                "createdAt": "2025-10-01T04:54:50.222695Z",
                "duration": "02:23:39",
                "id": "d81105da-c78a-482e-b1dc-d89e10d8d682",
                "sourceResolution": "720p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/82ee77ca-2cbf-49fd-8599-f35dcf66b6c1/thumbnail.png"
            },
            {
                "createdAt": "2025-10-01T07:20:48.857019Z",
                "duration": "00:27:52",
                "id": "3a4c6ced-baa8-4ef9-a15e-a0370fe8ef2d",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/f19268f5-9719-403f-87c9-b604fb3bdce3/thumbnail.png"
            }
        ],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T10:00:08.808521Z",
        "updatedAt": "2025-10-17T10:00:08.808521Z",
        "mediaCount": 2
    }
}

NOTE:
Smart playlists evaluate filters at creation time. To update the video list, create a new playlist with updated filters.


Play playlists

After you create a playlist, you can play it using the FastPix web player. The player handles video transitions automatically and provides playback controls.

Add the player to your page

Add the FastPix player element to your HTML and load the playlist.

In the following code, replace playbackId_1 and playbackId_2 with the actual playback IDs from your videos.

<fastpix-player id="player" aspect-ratio="16/9"></fastpix-player>

<script>
  const playlist = [
    { playbackId: 'playbackId_1' },
    { playbackId: 'playbackId_2' }
  ];

  const player = document.getElementById('player');
  player.addPlaylist(playlist);

  player.addEventListener('playbackidchange', (e) => {
    const { playbackId, currentIndex, totalItems } = e.detail || {};
    console.log('Now playing:', playbackId);
  });
</script>

Enable loop-next for playlists

By default, when a video in the playlist ends, playback stops. To automatically play the next video in the playlist, add the loop-next attribute to the player element:

<fastpix-player 
  id="player" 
  aspect-ratio="16/9"
  loop-next>
</fastpix-player>

With autoplay enabled:

The first video starts playing automatically when the page loads When a video ends, the next video in the playlist starts immediately. The playlist stops when the last video finishes.

NOTE:
Some browsers block autoplay with sound until you interact with the page. If autoplay fails, click the play button or interact with the page to start playback.


Update playlist details

You can modify a playlist's name and description after creation. This is helpful when refining naming conventions or updating descriptions to reflect content changes.

Send a PUT request to update playlist endpoint:

Replace {playlistId} with your playlist's identifier.

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}

Here's an example of the request body for updating playlist details:

Request body:

{
  "name": "Updated playlist name",
  "description": "Updated description"
}

NOTE:
You must include both name and description in the request, even if you're only changing one.


Here's an example of the response body for updating playlist details:

Response:

{
    "success": true,
    "data": {
        "id": "b3a0d94a-3233-4024-b127-76070ffe5431",
        "name": "Updated playlist name",
        "referenceId": "Set01",
        "type": "manual",
        "description": "updated description",
        "mediaList": [],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T09:40:50.147851Z",
        "updatedAt": "2025-10-17T10:18:11.086429Z",
        "mediaCount": 0
    }
}

IMPORTANT NOTES:

  • The playlistId must belong to a valid playlist in the authenticated user's workspace, or a 404 error is returned.
  • Both name and description must be non-empty strings.
  • Updating either value refreshes the updatedAt timestamp of the playlist.
  • The update does not affect the media list or type (manual or smart).

Get all playlists

Retrieve a paginated list of all playlists in your workspace. Use the limit and offset parameters to control how many playlists appear per page, making it easier to work with large collections.

Send a GET request to get all playlists endpoint:

https://api.fastpix.io/v1/on-demand/playlists/?limit={limit}&offset={offset}

Query parameters:

  • limit (optional): How many playlists to return in one page. Defaults to 10 if not specified.
  • offset (optional): Which page to retrieve, starting from 1 for the first page.

Response:

The endpoint returns playlist summaries with pagination information:

{
  "success": true,
  "data": [
    {
      "id": "db6e860f-cb57-43dd-8acf-39c9effd5608",
      "name": "playist",
      "type": "smart",
      "referenceId": "1n2",
      "createdAt": "2025-06-04T13:29:04.253244Z",
      "mediaCount": 0
    },
    {
      "id": "5c18559f-c1b1-4697-9282-77211d4396bb",
      "name": "playist",
      "type": "smart",
      "referenceId": "1n1",
      "createdAt": "2025-06-04T13:01:05.073809Z",
      "mediaCount": 0
    },
    {
      "id": "a4735902-b5e6-431f-8875-7a1a2cbc7a7b",
      "name": "okkokk",
      "type": "manual",
      "referenceId": "121q",
      "createdAt": "2025-06-04T12:17:38.917664Z",
      "mediaCount": 0
    }
  ],
  "pagination": {
    "totalRecords": 20,
    "currentOffset": 1,
    "offsetCount": 7
  }
}

Response structure:

Each playlist object includes:

  • id: Unique playlist identifier
  • name: Display title
  • type: Either manual or smart
  • referenceId: Your custom reference identifier
  • createdAt: Creation timestamp
  • mediaCount: Current number of videos

The pagination object provides:

  • totalRecords: Total playlists across all pages
  • currentOffset: Current page number
  • offsetCount: Number of playlists in this response

Get playlist details

To fetch information about a specific playlist, make a GET request with the playlist's unique identifier. This returns comprehensive playlist data including configuration settings, any date-based filters for smart playlists, and all videos currently in the playlist.

Send a GET request to get a playlist endpoint:

Replace {playlistId} with your playlist's identifier.

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}

Response:

The endpoint returns a detailed playlist object:

{
    "success": true,
    "data": {
        "id": "3bf8f24b-ca89-40a1-a3e9-170faf3de956",
        "name": "Test 1",
        "referenceId": "Set1",
        "type": "smart",
        "description": "Online Gaming Videos",
        "playOrder": "createdDate DESC",
        "metadata": {
            "createdDate": {
                "endDate": "2025-10-15",
                "startDate": "2025-09-01"
            }
        },
        "mediaList": [
            {
                "createdAt": "2025-10-01T07:20:48.857019Z",
                "duration": "00:27:52",
                "id": "3a4c6ced-baa8-4ef9-a15e-a0370fe8ef2d",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/f19268f5-9719-403f-87c9-b604fb3bdce3/thumbnail.png"
            },
            {
                "createdAt": "2025-10-01T04:54:50.222695Z",
                "duration": "02:23:39",
                "id": "d81105da-c78a-482e-b1dc-d89e10d8d682",
                "sourceResolution": "720p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/82ee77ca-2cbf-49fd-8599-f35dcf66b6c1/thumbnail.png"
            },
            {
                "createdAt": "2025-09-30T10:24:14.621213Z",
                "duration": "00:00:10",
                "id": "0c26cc32-a7eb-4f6c-a890-3670bbe10146",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/379f0e3a-c3f5-4060-b701-43763c7d05a4/thumbnail.png"
            },
            {
                "createdAt": "2025-09-30T10:24:04.032662Z",
                "duration": "00:00:10",
                "id": "7e6cee8d-d89a-4f0c-9c2a-03ec5cf7612f",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/a84fbc2f-1678-4f53-8ee2-bc1e778945f5/thumbnail.png"
            },
            {
                "createdAt": "2025-09-30T06:35:43.903460Z",
                "duration": "00:00:10",
                "id": "f3871af2-6942-4c59-8a5e-dd880829e412",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/45fd0881-5117-4b2c-b726-ac415399c2b1/thumbnail.png"
            },
            {
                "createdAt": "2025-09-24T10:50:55.594589Z",
                "duration": "00:03:17",
                "id": "82afefa8-b238-4ec5-8e39-1a6f5ea101de",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/597d8cc4-b387-4126-8f32-476a6e6fbe7b/thumbnail.png"
            },
            {
                "createdAt": "2025-09-23T06:10:17.589509Z",
                "duration": "00:00:10",
                "id": "65e83be9-0821-4bab-875f-7fc311c092c5",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/821041cc-9893-4856-9c8b-4388c26423ee/thumbnail.png"
            }
        ],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T09:44:30.111270Z",
        "updatedAt": "2025-10-17T10:42:20.353178Z",
        "mediaCount": 7
    }
}

Key response fields:

  • metadata: Contains filtering criteria for smart playlists. Manual playlists don't include this field.
  • playOrder: Specifies video sorting for smart playlists (such as createdDate DESC or createdDate ASC).
  • mediaList: Contains video objects with preview thumbnails and basic information.
  • mediaCount: Shows how many videos are currently in the playlist.

Add media to a playlist

Use this endpoint to insert one or multiple videos into an existing playlist. The bulk addition capability makes it straightforward to build and expand your playlists efficiently.

Send a PATCH request to add media to playlist endpoint:

Replace {playlistId} with your playlist's identifier.

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}/media

Here’s an example of the request body for adding media to a playlist:

Request body:

{ 
  "mediaIds": [ 
    "Media_ID1", 
    "Media_ID2"  
  ] 
}

NOTE:
The order in the mediaIds array determines the playback sequence. Videos already in the playlist are skipped.


Here’s an example of the response body for adding media to a playlist:

Response:

{
    "success": true,
    "data": {
        "id": "59d7960a-bab6-4c02-88ef-83b9ba992196",
        "name": "my smart playlist",
        "referenceId": "JanuaryToJune3",
        "type": "smart",
        "description": "This playlist contains videos created from January to june 2025",
        "playOrder": "createdDate ASC",
        "metadata": {
            "createdDate": {
                "endDate": "2025-02-17",
                "startDate": "2025-01-01"
            }
        },
        "mediaList": [
            {
                "createdAt": "2025-09-30T10:24:14.621213Z",
                "duration": "00:00:10",
                "id": "0c26cc32-a7eb-4f6c-a890-3670bbe10146",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/379f0e3a-c3f5-4060-b701-43763c7d05a4/thumbnail.png"
            }
        ],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T10:02:48.986053Z",
        "updatedAt": "2025-10-17T11:44:30.011848Z",
        "mediaCount": 1
    }
}

Parameters:

  • mediaIds (required): List of video identifiers to insert. Videos appear in the playlist in the order you specify here.

NOTE:
Videos already present in the playlist are automatically skipped. Duplicate IDs in your request are processed only once. The sequence in your mediaIds array controls the playback order, and the response includes the updated mediaCount.


Reorder medias in a playlist

Change the playback sequence by submitting a new arrangement of your playlist's media IDs. This operation restructures the entire playlist with your specified ordering.

NOTE:
This endpoint only rearranges existing videos. To insert new videos, use the add media endpoint.


Send a PUT request to change media order endpoint:

Replace {playlistId} with your playlist's identifier.

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}/media

Here’s an example of the request body for reordering medias in a playlist:

Request body:

{ 
  "mediaIds": [ 
    "Media_ID1", 
    "Media_ID2"  
  ] 
}

Here’s an example of the response body for reordering medias in a playlist:

Response body:

{
    "success": true,
    "data": {
        "id": "adad6a6d-6985-4ce9-ba9b-8ac0e08cdeb7",
        "name": "my smart playlist",
        "referenceId": "JanuaryToJune2",
        "type": "smart",
        "description": "This playlist contains videos created from January to june 2025",
        "playOrder": "createdDate ASC",
        "metadata": {
            "createdDate": {
                "endDate": "2025-10-17",
                "startDate": "2025-10-01"
            }
        },
        "mediaList": [
            {
                "createdAt": "2025-10-01T07:20:48.857019Z",
                "duration": "00:27:52",
                "id": "3a4c6ced-baa8-4ef9-a15e-a0370fe8ef2d",
                "sourceResolution": "1080p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/f19268f5-9719-403f-87c9-b604fb3bdce3/thumbnail.png"
            },
            {
                "createdAt": "2025-10-01T04:54:50.222695Z",
                "duration": "02:23:39",
                "id": "d81105da-c78a-482e-b1dc-d89e10d8d682",
                "sourceResolution": "720p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/82ee77ca-2cbf-49fd-8599-f35dcf66b6c1/thumbnail.png"
            }
        ],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T10:00:08.808521Z",
        "updatedAt": "2025-10-17T11:59:46.214536Z",
        "mediaCount": 2
    }
}

Parameters:

  • mediaIds (required): Complete list of all video IDs currently in the playlist, arranged in your desired sequence. Every existing video must appear in this array.

NOTE:
Include all existing videos in your new order. Omitting any video causes a validation error. Partial reordering isn't available, you must specify the complete sequence. To add videos while reordering, first use the add media endpoint, then reorder.


Remove media from a playlist

Delete specific medias from a playlist while preserving the remaining content and its sequence. This lets you refine playlists without rebuilding them from scratch.

NOTE: This operation only removes medias from the playlist. Your original media files remain in your workspace.

Replace {playlistId} with your playlist's identifier.

Send a DELETE request to Delete media from playlist endpoint:

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}/media

Here’s an example of the request body for removing media from a playlist:

Request body:

{ 
  "mediaIds": [ 
    "Media_ID" 
  ] 
}

Here’s an example of the response body for removing media from a playlist:

Response body:

{
    "success": true,
    "data": {
        "id": "adad6a6d-6985-4ce9-ba9b-8ac0e08cdeb7",
        "name": "my smart playlist",
        "referenceId": "JanuaryToJune2",
        "type": "smart",
        "description": "This playlist contains videos created from January to june 2025",
        "playOrder": "createdDate ASC",
        "metadata": {
            "createdDate": {
                "endDate": "2025-10-17",
                "startDate": "2025-10-01"
            }
        },
        "mediaList": [
            {
                "createdAt": "2025-10-01T04:54:50.222695Z",
                "duration": "02:23:39",
                "id": "d81105da-c78a-482e-b1dc-d89e10d8d682",
                "sourceResolution": "720p",
                "status": "Ready",
                "thumbnail": "https://images.fastpix.io/82ee77ca-2cbf-49fd-8599-f35dcf66b6c1/thumbnail.png"
            }
        ],
        "workspaceId": "ca166f53-8a64-4c5e-872a-b97185d69897",
        "createdAt": "2025-10-17T10:00:08.808521Z",
        "updatedAt": "2025-10-17T12:06:12.797825Z",
        "mediaCount": 1
    }
}

Parameters:

  • mediaIds (required): List of video IDs to remove. Each ID must belong to a video currently in the playlist.

NOTE:
Specifying a video ID that doesn't exist in the playlist triggers a validation error. The playlist structure remains intact, with only the specified videos removed. All other videos maintain their original positions.


Delete a playlist

Permanently remove a playlist from your workspace. The playlist disappears from all listings, but videos within it remain available in your media library.

Caution: Deletion is irreversible. After removed, playlists cannot be restored. Exercise caution with playlists used in production or shared with others.

Send a DELETE request to Delete a playlist endpoint:

Replace {playlistId} with the identifier of the playlist to delete.

https://api.fastpix.io/v1/on-demand/playlists/{playlistId}

Response:

{
  "success": true
}

The playlist is permanently removed and cannot be recovered. Medias contained in the playlist remain in your media library, only the playlist structure is deleted. Invalid or non-existent playlist IDs return a 404 error.


Best practices

Follow these recommendations when working with playlists:

  • Choose the right playlist type. Use manual playlists for curated content and smart playlists for dynamic collections based on metadata.
  • Use descriptive names and reference IDs. Clear naming helps you manage playlists at scale and makes API integration easier.
  • Stay within limits. Each playlist supports up to 1,000 videos. For larger collections, create multiple playlists.
  • Test playback before deployment. Verify video order, transitions, and autoplay behavior work as expected.
  • Monitor browser compatibility. Autoplay policies vary across browsers. Provide fallback controls for users.

Common use cases

Manual playlists

  • Featured content collections
  • Product showcase series
  • Training or educational modules
  • Brand highlight reels

Smart playlists

  • Recent uploads ("Videos from this week")
  • Time-based collections ("March 2025 content")
  • Event-specific compilations
  • Scheduled publishing workflows

Troubleshooting

Playlist creation fails

If playlist creation returns an error:

  • Verify the reference ID is unique within your workspace
  • Check that all required fields are included
  • Confirm your API credentials have the necessary permissions

Videos don't auto-play

If automatic playback doesn't work:

  • Ensure the loop-next attribute is set on the player element
  • Check browser console for autoplay policy restrictions
  • Test with user interaction (for example, a click) to enable autoplay

Smart playlist returns no results

If your smart playlist is empty:

  • Verify videos exist within the specified date range
  • Check that the date format is correct (DD-MM-YYYY)
  • Confirm the start date is before the end date

Updated 2 months ago