Chromecast Integration

Relevant source files

The following files were used as context for generating this wiki page:

• Putio/Features/Chromecast/ChromecastManager.swift
• Putio/Features/Files/FilesViewController.swift
• Putio/Features/Files/FilesViewController+Navigation.swift
• Putio/Features/Files/FilePresenter.swift
• Putio/Features/Settings/SettingsViewModel+Sections.swift
• Putio/AppDelegate.swift
• Putio/Common/API/PutioSDK.swift
• PutioTests/UserConfigTests.swift

Chromecast Integration in the put.io iOS application allows users to discover Google Cast-enabled devices and stream video content directly from their put.io cloud storage to a television or secondary display. The system leverages the Google Cast SDK to manage discovery, session establishment, and media playback control.

The integration is centered around a singleton manager that handles the lifecycle of cast sessions, UI stylization for cast components, and the mapping of put.io file metadata and subtitles to Google Cast media objects. It integrates deeply with the application's file browsing and settings modules to provide a seamless transition from local mobile playback to remote casting.

Sources: Putio/Features/Chromecast/ChromecastManager.swift, Putio/AppDelegate.swift:150-155

Core Architecture

The Chromecast system is managed by the ChromecastManager class, which acts as a centralized controller for all Google Cast operations. It is initialized during the application's main screen presentation.

ChromecastManager Lifecycle

The manager is responsible for setting up the GCKCastContext with specific discovery criteria and application identifiers. It also serves as a listener for session events and a delegate for logging.

UI Components and Styling

The integration includes native UI elements for user interaction:

• GCKUICastButton: Displayed in the navigation bar of file lists to allow users to connect to devices.
• Expanded Controls: The manager enables useDefaultExpandedMediaControls to provide a full-screen remote control interface.
• Custom Styling: The stylize() function applies put.io branded colors (e.g., UIColor.Putio.yellow, UIColor.Putio.background) to the Google Cast views, including sliders, text, and icons.

Sources: Putio/Features/Chromecast/ChromecastManager.swift:42-88, Putio/Features/Files/FilesViewController+Navigation.swift:20-30

Media Playback Logic

Casting a video involves retrieving file data from the put.io API and converting it into GCKMediaInformation.

Playback Flow

When a user selects a file for casting, the application verifies if a cast session is active. If active, the castVideo(fileID:completion:) method is invoked.

Playback Types

The system supports two primary streaming formats, which can be toggled in the application settings:

1. HLS (HTTP Live Streaming): Used if chromecastPlaybackType is set to "hls". It uses the M3U8 stream URL and video/m3u content type.
2. MP4: The default streaming format, using either the original stream URL or the MP4-converted URL if available.

Feature	HLS Configuration	MP4 Configuration
Content ID	file.getHlsStreamURL	file.mp4StreamURL or file.streamURL
Content Type	video/m3u	video/mp4
Stream Type	.none	.buffered

Sources: Putio/Features/Chromecast/ChromecastManager.swift:131-144, Putio/Features/Settings/SettingsViewModel+Sections.swift:101-111

Metadata and Subtitles

ChromecastManager maps PutioFile properties to GCKMediaMetadata to ensure titles, subtitles, and thumbnails appear correctly on the TV screen.

Metadata Mapping

• Title: Mapped from file.name.
• Subtitle: Formatted as put.io/files/{id}.
• Thumbnail: Generated from file.screenshot at a resolution of 640x360.

Sources: Putio/Features/Chromecast/ChromecastManager.swift:94-112

Subtitle Integration

The manager fetches subtitles via api.getSubtitles(fileID:). Each subtitle is converted into a GCKMediaTrack with:

• Content Identifier: The subtitle URL appended with &format=webvtt.
• Content Type: text/vtt.
• Auto-selection: Controlled by userSettings.dontAutoSelectSubtitles. If auto-selection is enabled, the first track (index 0) is activated by default.

Sources: Putio/Features/Chromecast/ChromecastManager.swift:149-173

Progress Tracking and Sync

The system includes a mechanism to save playback progress back to the put.io servers while casting.

Progress Synchronization

1. Start Position: When loading media, mediaLoadOptions.playPosition is set to the value of file.startFrom.
2. Periodic Updates: A Timer is scheduled every 15 seconds during an active cast session.
3. Progress Persistence: The manager calls saveVideoTime(), which retrieves the approximateStreamPosition() from the remoteMediaClient and updates the server via api.setStartFrom(fileID:time:completion:).
4. Session End: The timer is invalidated when the session ends or fails to start.

Sources: Putio/Features/Chromecast/ChromecastManager.swift:114-119, Putio/Features/Chromecast/ChromecastManager.swift:221-236, Putio/Features/Chromecast/ChromecastManager.swift:239-261

Error Handling

The integration defines specific error reasons to handle edge cases during the casting process.

Error Reason	Trigger Condition	UI Response
fileNotFound	API fails to return file data.	Generic casting error alert.
fileNeedsConvert	File is not H264 and needConvert is true.	Presents the Video Conversion View.
missingMetadata	file.metaData is nil during media info building.	Generic casting error alert.

Sources: Putio/Features/Chromecast/ChromecastManager.swift:12-18, Putio/Features/Files/FilePresenter.swift:78-91