User Preferences & Display Settings

API endpoints for managing user display preferences, UI settings, and client-specific configurations

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

Show Common custom preferences

chromecastVersion · string

Chromecast version: “stable” or “unstable”

skipForwardLength · string

Skip forward length in milliseconds (default: “30000”)

skipBackLength · string

Skip backward length in milliseconds (default: “10000”)

enableNextVideoInfoOverlay · string

Whether to show next video overlay: “true” or “false”

dashboardTheme · string

Dashboard theme name

tvhome · string

TV home screen configuration

homesection[0-7] · string

Home section types: “smalllibrarytiles”, “resume”, “resumeaudio”, “resumebook”, “livetv”, “nextup”, “latestmedia”, “none”

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