Skip to main content

​
Overview

The Display Preferences API allows users to customize their viewing experience, including sort order, view types, home screen layout, and client-specific settings. These preferences are stored per user, per client, and per item/view.

​
Get Display Preferences

Retrieves display preferences for a specific item or view. Endpoint: GET /DisplayPreferences/{displayPreferencesId} Authorization: Required

​
Path Parameters

​
displayPreferencesId
string
required
The ID of the item or view. Can be a GUID or a string identifier (which will be hashed to MD5).

​
Query Parameters

​
userId
string (UUID)
The user ID. If not provided, uses the authenticated user.
​
client
string
required
The client application name (e.g., “web”, “Android”, “iOS”)

​
Response

​
Id
string
The display preferences identifier
​
Client
string
The client application name
​
ViewType
string
The view type (e.g., “Movies”, “TvShows”, “Music”)
​
SortBy
string
The field to sort by (e.g., “SortName”, “DateCreated”, “PremiereDate”)
​
SortOrder
string
Sort order: “Ascending” or “Descending”
​
IndexBy
string
How to index items (e.g., “None”, “Premiere”, “ProductionYear”)
​
RememberIndexing
boolean
Whether to remember the indexing preference
​
RememberSorting
boolean
Whether to remember the sorting preference
​
ScrollDirection
string
Scroll direction: “Horizontal” or “Vertical”
​
ShowBackdrop
boolean
Whether to display backdrop images
​
ShowSidebar
boolean
Whether to show the sidebar
​
PrimaryImageHeight
integer
Height of primary images in pixels
​
PrimaryImageWidth
integer
Width of primary images in pixels
​
CustomPrefs
object
Dictionary of custom preference key-value pairs

​
Status Codes

  • 200 - Display preferences retrieved successfully

​
Example Request

curl -X GET "https://your-server.com/DisplayPreferences/f6f3a5e4-5e4f-4e4f-8e4f-5e4f6f3a5e4f?client=web" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

​
Example Response

{
  "Id": "f6f3a5e4-5e4f-4e4f-8e4f-5e4f6f3a5e4f",
  "Client": "web",
  "ViewType": null,
  "SortBy": "SortName",
  "SortOrder": "Ascending",
  "IndexBy": null,
  "RememberIndexing": false,
  "RememberSorting": true,
  "ScrollDirection": "Horizontal",
  "ShowBackdrop": true,
  "ShowSidebar": false,
  "PrimaryImageHeight": 250,
  "PrimaryImageWidth": 250,
  "CustomPrefs": {
    "chromecastVersion": "stable",
    "skipForwardLength": "30000",
    "skipBackLength": "10000",
    "enableNextVideoInfoOverlay": "true",
    "dashboardTheme": "dark",
    "homesection0": "smalllibrarytiles",
    "homesection1": "resume",
    "homesection2": "nextup",
    "homesection3": "latestmedia"
  }
}

​
Update Display Preferences

Updates display preferences for a specific item or view. Endpoint: POST /DisplayPreferences/{displayPreferencesId} Authorization: Required

​
Path Parameters

​
displayPreferencesId
string
required
The ID of the item or view

​
Query Parameters

​
userId
string (UUID)
The user ID. If not provided, uses the authenticated user.
​
client
string
required
The client application name

​
Request Body

​
ViewType
string
The view type
​
SortBy
string
The field to sort by (e.g., “SortName”, “DateCreated”, “CommunityRating”)
​
SortOrder
string
Sort order: “Ascending” or “Descending”
​
IndexBy
string
Indexing method: “None”, “Premiere”, “ProductionYear”, “CommunityRating”
​
RememberIndexing
boolean
Whether to remember indexing preference
​
RememberSorting
boolean
Whether to remember sorting preference
​
ScrollDirection
string
Scroll direction: “Horizontal” or “Vertical”
​
ShowBackdrop
boolean
Whether to show backdrop images
​
ShowSidebar
boolean
Whether to show the sidebar
​
CustomPrefs
object
Dictionary of custom preferences (any key-value pairs)

​
Response

Returns 204 No Content on success.

​
Status Codes

  • 204 - Display preferences updated successfully

​
Example Request

curl -X POST "https://your-server.com/DisplayPreferences/f6f3a5e4-5e4f-4e4f-8e4f-5e4f6f3a5e4f?client=web" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ViewType": null,
    "SortBy": "DateCreated",
    "SortOrder": "Descending",
    "IndexBy": null,
    "RememberIndexing": false,
    "RememberSorting": true,
    "ScrollDirection": "Horizontal",
    "ShowBackdrop": true,
    "ShowSidebar": false,
    "CustomPrefs": {
      "chromecastVersion": "stable",
      "skipForwardLength": "45000",
      "skipBackLength": "15000",
      "enableNextVideoInfoOverlay": "true",
      "dashboardTheme": "light",
      "homesection0": "resume",
      "homesection1": "nextup",
      "homesection2": "latestmedia",
      "homesection3": "livetv"
    }
  }'

​
Display Preferences Concepts

​
Client-Specific Preferences

Display preferences are stored separately for each client application. This allows users to have different settings on different devices:
  • Web client: Desktop browser settings
  • Android: Mobile app settings
  • iOS: iOS app settings
  • Roku, Apple TV, etc.: Device-specific settings
Each client can maintain its own preferences for sorting, view types, and custom settings.

​
Item-Specific Preferences

Preferences can be set for individual items or views:
  • Library folders: Each library (Movies, TV Shows, Music) can have its own display settings
  • Collections: Custom collections can have unique view preferences
  • Special views: “Latest”, “Favorites”, etc., can each have different settings

​
Home Section Configuration

The home screen layout is controlled through custom preferences with keys homesection0 through homesection7. Available section types:
  • SmallLibraryTiles: Compact library view
  • Resume: Continue watching/listening
  • ResumeAudio: Continue listening (audio)
  • ResumeBook: Continue reading (books)
  • LiveTv: Live TV section
  • NextUp: Next episodes to watch
  • LatestMedia: Recently added media
  • None: Empty section

​
Sorting Options

Common sorting fields:
  • SortName: Alphabetical by name
  • DateCreated: Date added to library
  • DatePlayed: Last played date
  • PremiereDate: Original release date
  • CommunityRating: User ratings
  • CriticRating: Critic ratings
  • ProductionYear: Year produced
  • PlayCount: Number of plays
  • Budget: Production budget (movies)
  • Revenue: Box office revenue (movies)
  • Runtime: Duration

​
Indexing Options

Indexing creates alphabetical or categorical groupings:
  • None: No indexing
  • Premiere: Group by premiere date
  • ProductionYear: Group by year
  • CommunityRating: Group by rating range

​
Common Use Cases

​
Setting Skip Lengths

Customize skip forward/backward button behavior: 
{
  "CustomPrefs": {
    "skipForwardLength": "30000",  // 30 seconds
    "skipBackLength": "10000"      // 10 seconds
  }
}

​
Configuring Home Screen

Set up a custom home screen layout: 
{
  "CustomPrefs": {
    "homesection0": "resume",
    "homesection1": "nextup",
    "homesection2": "latestmedia",
    "homesection3": "smalllibrarytiles",
    "homesection4": "none",
    "homesection5": "none",
    "homesection6": "none",
    "homesection7": "none"
  }
}

​
Setting Library View Preferences

Configure how a library displays items: 
{
  "SortBy": "PremiereDate",
  "SortOrder": "Descending",
  "IndexBy": "ProductionYear",
  "RememberSorting": true,
  "RememberIndexing": true,
  "ShowBackdrop": true
}

​
Theme Configuration

Set dashboard theme: 
{
  "CustomPrefs": {
    "dashboardTheme": "dark"  // or "light"
  }
}

​
Best Practices

  1. Always specify the client: Different clients may have different capabilities and UI layouts
  2. Use item-specific IDs: Display preferences should be set for specific libraries or views, not globally
  3. Preserve existing preferences: When updating, include all current CustomPrefs keys to avoid losing unrelated settings
  4. Validate custom values: Ensure custom preference values are valid before saving (e.g., numeric strings for skip lengths)
  5. Handle defaults gracefully: If preferences don’t exist, the server returns sensible defaults
  6. Test across clients: Verify that custom preferences work correctly on all target client applications

Build docs developers (and LLMs) love

Get started for freeTalk to us