Video Conversion (MP4)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Video Conversion (MP4) is a critical utility in the put.io iOS application designed to ensure media compatibility across various playback scenarios. Its primary purpose is to convert video files that are not natively supported by iOS or specific hardware targets (like Chromecast) into a compatible MP4 format. This process is essential for providing a seamless user experience, allowing users to stream or download media that would otherwise be unplayable on their devices.
Sources: Putio/Features/Files/VideoConversionViewController.swift:10-12, Putio/Features/Files/FilePresenter.swift:16-18
The system operates by checking a file's conversion requirements before playback or download. If a file requires conversion, the application triggers a remote conversion process via the put.io API and provides a dedicated user interface to track progress in real-time. Once the conversion reaches a "completed" state, the app automatically transitions to the intended action, such as launching the media player.
Sources: Putio/Features/Files/VideoConversionViewController.swift:76-88, Putio/Features/Files/FilePresenter.swift:16-20
Architecture and Workflow
The conversion system follows a delegation pattern where a presenter triggers the conversion view, which then manages the lifecycle of the API requests.
Triggering Mechanisms
Conversion is typically triggered during file navigation or when attempting to cast media. The FilePresenter and ChromecastManager evaluate the needConvert flag on a PutioFile object. If true, the presentVideoConversionView method is called.
Sources: Putio/Features/Files/FilePresenter.swift:16-18, Putio/Features/Chromecast/ChromecastManager.swift:156-158
Conversion Process Flow
The following diagram illustrates the sequence of events from detecting the need for conversion to the eventual playback of the converted file.
Component Breakdown
VideoConversionViewController
This controller manages the visual representation of the conversion progress. It utilizes a UIProgressView and a UILabel to inform the user of the current state.
VideoConversionIntention: An enum defining the post-conversion action:.playor.download.startConversion(): Initiates the conversion request via the SDK.checkConversionStatus(): A recursive function (using 3-second delays) that polls the API for the current conversion state.
Sources: Putio/Features/Files/VideoConversionViewController.swift:10-25, Putio/Features/Files/VideoConversionViewController.swift:76-104
Conversion States
The system maps API status responses to user-friendly strings and progress values.
| Status Enum | Label Shown to User | Logic / Result |
|---|---|---|
.queued | In Queue | Conversion request accepted, waiting for worker. |
.converting | Converting... | File is currently being processed. |
.completed | Completed, video will automatically play! | Conversion finished; triggers automatic dismissal. |
.error / .notAvailable | Error | Stops polling and notifies user of failure. |
Sources: Putio/Features/Files/VideoConversionViewController.swift:30-49, Putio/Common/API/PutioSDK.swift:23-25
API Integration
The conversion feature relies on specific endpoints within the PutioSDK.
Key SDK Methods
startMp4Conversion(fileID:): CallsPOST /v2/files/{id}/mp4to begin the process.getMp4ConversionStatus(fileID:): CallsGET /v2/files/{id}/mp4to retrieve aPutioMp4Conversionobject containing status and percentage.
Sources: Putio/Common/API/PutioSDK.swift:150-160, Putio/Common/API/PutioE2EMockURLProtocol.swift:63-64
Mock Data Structure (E2E)
During testing, the mock API provides the following structure for conversion status:
{
"mp4": {
"status": "COMPLETED",
"percent_done": 100,
"start_from": 0
}
}
Sources: Putio/Common/API/PutioE2EMockURLProtocol.swift:174-181
Chromecast Specifics
Chromecast support adds a layer of complexity. Since Chromecast primarily supports H264 codecs, a check is performed to see if the file's codec requires conversion even if the general needConvert flag is not high-priority for local playback. If file.needConvert is true and the codec is not h264, the conversion view is presented before casting starts.
Sources: Putio/Features/Chromecast/ChromecastManager.swift:156-158, Putio/Features/Files/FilePresenter.swift:80-84
Conclusion
The Video Conversion module is a specialized pipeline that bridges the gap between stored media formats and iOS playback capabilities. By abstracting the polling and status management into VideoConversionViewController, the application maintains a responsive UI while handling long-running server-side conversion tasks. Its integration into the FilePresenter ensures that conversion is a frictionless gatekeeper for media consumption across local and remote (Chromecast) endpoints.