Developers of third-party apps and services can take advantage of VidHub's video playback capabilities and play videos using URL schemes. It also supports x-callback, allowing to return to another app after the operation is completed.
Available platforms: iPhone, iPad

Usage Examples

Play a single file and return to another application when finished

open-vidhub://x-callback-url/open?
on-success=some-app://x-callback-url/success&
on-failed=some-app://x-callback-url/failed&
url=http://localhost:8080/sample.mp4

Play a single file with external subtitles added

open-vidhub://x-callback-url/open?
on-success=some-app://x-callback-url/success&
on-failed=some-app://x-callback-url/failed&
url=http://localhost:8080/sample.mp4&
sub=http://localhost:8080/sample.srt

URL Encoding

All query string values ​​should be URL-encoded per the x-callback-url specification. Unencoded URLs may work in some cases, but you may need to manually URL-encode when using actions with multiple parameters or URLs with multiple keys.

Original URL

http://localhost:8080/Movies/movie.mkv

Encoded URL

http%3A%2F%2Flocalhost%3A8080%2Fsample.mp4

3rd-party integration examples

Third-party applications can call this method to pass video files or subtitles to VidHub for playback.

func openWithVidHub(url: URL, subUrl: URL? = nil) {
    let urlString = url.isFileURL ? url.path.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) : url.absoluteString.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)
    // Create with URLComponents
    var components = URLComponents()
    components.scheme = "open-vidhub"
    components.host = "x-callback-url"
    components.path = "/open"
    var queryItems: [URLQueryItem] = [URLQueryItem]()
    queryItems.append(URLQueryItem(name: "url", value: urlString))
    
    // subtitles, optional
    if let subUrl = subUrl, 
        let subUrlString = subUrl.isFileURL ? subUrl.path.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) : subUrl.absoluteString.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed){
      queryItems.append(URLQueryItem(name: "sub", value: subUrlString))
    }
    
    // Optionally, you can also add callback urls in queryItems
    queryItems.append(URLQueryItem(name: "on-success", value: "mySchema://x-callback-url/success".addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)))
    queryItems.append(URLQueryItem(name: "on-failed", value: "mySchema://x-callback-url/failed".addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)))
    
    components.queryItems = queryItems
    
    guard let vidHubURL = components.url else {
      return
    }

    debugPrint("Open with VidHub: \(vidHubURL.absoluteString)")

    UIApplication.shared.open(vidHubURL, options: [:], completionHandler: nil)
  } 

You can also call scene(_:openURLContexts:) to handle callback methods from VidHub.

  func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
      return
    }
    // Process api call from VidHub
    // mySchema://x-callbacksw-url/success or mySchema://x-callback-url/failed
    if url.scheme == "mySchema" {
      if url.host == "x-callback-url" {
        if url.path == "/success" {
          // Handle success
          debugPrint("Success")
        } else if url.path == "/failed" {
          // Handle failed
          debugPrint("Failed")
        }
      }
    }    
  }

iCloud allows information synchronization between multiple devices, such as file sources, media libraries, watch history, playlists, bookmarks, and media servers.
Log in with the same iCloud ID on all devices.
Enable iCloud Drive on all devices.
Go to VidHub > Settings > Sync > iCloud Sync.
Ensure that iCloud has enough storage space for the required synchronization.
Run the latest version of iCloud on all devices.
(Note: Insufficient or full iCloud storage may result in imported files being lost or video playback errors.)

• Spoiler Hiding: When enabled, the episode details page won't display episode summaries. When disabled, episode summaries are shown.
• Media Sorting: Set the default sorting method for browsing media.
• File Sorting: Set the default sorting method for browsing files.
• Appearance: Choose between a black or white user interface or automatically follow the system setting.
• Online Media Data Language: Change the language for online media data or automatically detect based on the system language.
• Allow Cellular Data: Enable or disable the use of cellular data for downloading.
• Concurrent Downloads: Set the maximum number of simultaneous video downloads.
• Display Floating Window: Show or hide a small floating window during downloads.
• Pause Downloads During Playback: When enabled, video downloads will automatically pause during playback. When disabled, downloads will continue while playing.

Resources

• Media Library: Display the current number of movie types available.
• Refresh File Sources: Rescan video files in all file sources to detect changes and sync them to the media library.
• Refresh Online Media Data: Retrieve updated information for movies and TV shows from the TMDB website. Executing this operation is necessary if changes have been made to the language setting for online media data.
• File Sources: Enable or disable file sources by checking or unchecking them.

Downloads

• View and manage locally downloaded videos.

Sync

• iCloud Sync: Enable iCloud synchronization for detailed media library information.

Playback

• Fast Forward Interval/Rewind Interval: Set the time interval for each fast forward or rewind action.
• Playback Behavior for Ali/Baidu Cloud Videos: Choose to play the original quality or the highest resolution video stream when playing Ali/Baidu Cloud videos.
• Continual Playback: Automatically play the next episode when enabled. Disable to prevent automatic playback.
• Background Playback: Allow video playback to continue when the app is in the background.
• Remember Playback Speed: Preserve the playback speed set before quitting and resume with the same speed on the next use.
• Hardware Acceleration: Optimize playback using hardware acceleration.
• Cache to Disk: Enable or disable disk caching.

Player Interface

• Auto Hide Player Controls: Set the time for automatically hiding the player controls.
• Time Display on Progress Bar: Choose to display the total video duration or remaining time on the progress bar.
• Long Press for Playback Speed: Select the playback speed by long-pressing on the screen.
• Double Tap for Fast Forward/Rewind: Enable or disable double-tap gestures for fast forwarding or rewinding.
• Show Screenshot/Screen Recording Button: Show or hide the screenshot and screen recording buttons.
• Default Landscape View: Enable or disable default landscape display for videos.
• Player Control Panel Background Shadow: Enable or disable background shadow for the player control panel.

Subtitles

• Automatically Load External Subtitles: Choose the rules for automatically loading subtitle files.
• Automatically Load Built-In Subtitles: Enable or disable automatic loading of built-in subtitles.
• Automatically Load Built-In Subtitle Language: Select the language for automatically loading built-in subtitles (note: supported subtitle/language availability may vary).
• Online Subtitle Search Language: Select the language for online subtitle searches (note: supported subtitle/language availability may vary).

Screenshots and Screen Recording

• Image Format: Choose the image format for screenshots.
• GIF Frame Rate: Select the frame rate for GIFs.
• GIF Resolution: Choose the resolution for GIFs.

Video playback operation interface: left

1.Screen Lock: The button with a lock icon on the left side is used to lock the screen. When the button is white and open, you can interact with the current interface. When it is closed and green, no "operations" can be performed on the current interface, and you can only click the lock button again to unlock it.
Note: When the screen is locked, all other icons will be hidden. Clicking again will show them.
2.Video Rotation: The green state represents the current landscape mode. If clicked and turned white, it becomes portrait mode.
3.Episode Selection: The icon with three horizontal bars at the bottom left will show all movie files in the same folder when clicked. If there is only one movie file in the folder, this button will not be displayed.
4.Resolution: The Original button at the bottom is used to set the resolution. Clicking on it will expand the available resolution options.
Note: If the video is imported from WebDAV/Alist, the resolution will not be displayed. If there is only one file in the folder and it is imported from WebDAV/Alist, neither the episode selection nor the resolution will be displayed.

Playback Controls: Right Side

1.Snapshot: The icon in the middle on the right side, represented by a camera-style image, is used for taking snapshots. Clicking on it captures the current frame of the video. (This function can be used during both playback and pause.)
2.GIF: Clicking on the GIF icon starts recording a GIF image. Clicking again generates the GIF and saves it to the photo album. To close the GIF recording window, simply click anywhere blank on the screen. (If the video is paused while using the GIF function, it will automatically resume playing.)
3.Fit to Screen: Clicking on this option adjusts the video to fit the screen size.
4.Subtitles: Allows selection of subtitle display options.
5.Playback Speed: Clicking on this option enables selection of the video playback speed.
6.Screen Mirroring: By clicking on the computer-style icon at the top, you can mirror the mobile screen to an Apple TV.

More Options (Three Dots) in the upper-right corner

1.Clicking on the "More" option displays the video settings. If you are not familiar with the equalizer, it is recommended not to adjust the values as it may cause color deviations.

2.The audio track setting defines the way and volume at which the sound is played. Disabling it will result in no sound. (If you are not familiar with the equalizer, it is recommended not to adjust the values as it may cause audio deviations.)

3.In the subtitle settings, if the video has embedded subtitles, you can disable the main subtitles. If you need to load your own local subtitles, click the button to select and load the local subtitles (the subtitle file should be in the same folder as the video file and have the same name).
3.1. There is a code option when scrolling down. If you encounter garbled characters while using local subtitles, click on the code option, select the language of the loaded local subtitles, and then fast forward a bit to resolve the issue.

When a video is incorrectly scraped or classified as "Other," use this feature to change the corresponding file to the correct movie/TV show.

Accessing the Feature

For individual movies and videos in the "Other" category:
Long press on (right-click on macOS) the video poster in the media library, then select the "Edit Information" option. Alternatively, go to the movie details page and click on the three dots in the top right corner, then click on "Edit Information."

Movie Collection/TV Series
Go to the movie details page, select a single episode, click on the three dots in the top right corner, and then click on "Edit Information."

Function Usage Introduction

1.Input Box: The input box in the edit information interface allows you to search for a movie name. Select the corresponding movie from the search results, and the information of the movie being edited will be replaced with the selected movie.
2.Change to Movie: For movies in other categories, after finding the correct movie information through search, apply it to move the movie to the movie category.
3.Change to TV Show: For movies in other categories, after finding the correct TV show information through search, apply it to move the movie to the TV show category.
4.Use Original File Data: For movies in the movie/TV show category, selecting to use the original file data will move the movie to the other category.


3.1. TV Series: If you want to edit a TV series, first go to the movie details page, select any episode from a specific season, click on the three dots in the top right corner, and then click on "Edit Information." After searching and selecting the TV series you want to modify, make the necessary changes. Wait for a moment, and the information of all other episodes in the same season will be automatically updated.

After entering the file source, long-press the individual folder/file and click on "Rename". A rename popup will appear. Enter the new name and click "Save". The folder/file will then be renamed with the new name.

Batch Rename

After entering the file source, click on the three dots in the upper right corner of the file source, then click on "Edit". Next, click on the three dots in the lower right corner to enable multiple selection of files/folders for renaming.

Batch Renaming of Previously Selected Folders/Files

Add Text:

This refers to the renaming method where new text is added to the original file name.
If the input is placed before the name, the content will be displayed before the original name.
If the input is placed after the name, the content will be displayed after the original name.
For example: Adding "123" before the name will result in all file names being prefixed with "123".

Replace Text

This refers to the renaming method where certain text in the original file name is replaced with new text.

Enter the text "A" to be replaced with in the "Search" input box, and enter the replacement text "B" in the "Replace with" input box. The text "A" in the file names will all be replaced with text "B".

For example, if you input "Doctor" in the search box and "123" in the replace with box, after renaming, all occurrences of "Doctor" in the file names will be replaced with "123".

Formatting

Formatting refers to the renaming method where a numerical index is added uniformly to the original file names.
Custom Format: This allows for the reconfiguration of the file names.
Starting Index: The index number can represent the season or episode number of a TV show.
After/Before Name: The index number can be added after or before the custom format. After renaming, the file names will become "{custom format}{index number}" or "{index number}{custom format}".
For example, if the custom format is set as "Test" and you choose to place the index number after the name, the file will be renamed as "Test01". If placed before, it will be "01Test".
Fixed Length: Specifies the number of digits for displaying the index number.
For example, for an index number of "1", if the fixed length is set to 1, it will be displayed as "1". If the fixed length is 2, it will be displayed as "01". If the fixed length is 3, it will be displayed as "001".
As shown in the example below, if the custom format is set as "Fast and Furious S01E" and the index is placed after the name, and the starting index is set as "5" with a length of 2 digits ("5" displayed as "05"), the selected files will be renamed as "Fast and Furious S01E05" and "Fast and Furious S01E06".

Regular expressions

Advanced replacement functionality refers to the method of using regular expressions to replace certain text with new text
Enter the text you want to replace in the regular expression box, for example, "\d{3}", which represents any three digits. In the replacement input box, enter the text B you want to replace with. Any three digits in the original file will be replaced with the text B
Note: Please search for how to use regular expressions.

If the automatically matched movie or TV show is incorrect, you can modify the filename or manually edit the information to correct it.
Rename File: Single File/Batch Rename.
Manually Edit Information.

Correct Naming for Movies

The file name should start with the complete name of the movie. For example:
The.Irishman.1080p.x264.mp4

If there are movies with the same name, it is necessary to include the release date in the filename. For example:
The.Irishman.2019.1080p.x264.mp4

Correct Naming for TV Shows (Including variety shows and animations)

Each episode within the same TV show should start with the show name (in either Chinese or English), followed by the season and episode information. For example: S01 = Season 1, S02 = Season 2, E01 = Episode 1, E02 = Episode 2. For example:
Shameless.S01E01.1080p.AMZN.WEB.DL.mkv
Meaning: Shameless Season 1 Episode 1

Shameless.S03E02.1080p.AMZN.WEB.DL.mkv
Meaning: Shameless Season 3 Episode 2

If there are tv shows with the same name, it is necessary to include the first air date of the tv show in the filename. For example:
Shameless.2011.S05E01.1080p.AMZN.WEB.DL.mkv

Specials and Extras for TV Shows

For TV show specials and extras, the filename should start with the show name, followed by the season information (use 00), and specify the episode number. For example:
Shameless.S00E01.1080p.AMZN.mkv
Meaning: Shameless Special Episode 1

All the long press operations below are for mobile versions, and the corresponding desktop versions are right-click operations.

Single File Operations

Rescan Files (File Source/Folder)

Long-press Added File Source or Folder in the Added File Source to rescan all video files in that File Source/Folder. Any newly added, deleted, or renamed video files will be synced to the media library. Alternatively, you can enter folder A, click the three dots in the upper right corner, and select "Rescan Files" from the menu.

Rename

In VidHub, renaming files or folders in the file source will directly changes the original filenames. The media center will refreshed based on the new filenames automatically. View video file naming conventions

Download (File)

Long-press a file to bring up a selection box. Clicking "Download" will download the video to local storage. Downloaded files can be viewed in Settings -> Downloads.

Delete

Deleting files or folders within the file source in VidHub directly removes the original files. The media library will rescan and sync based on the deleted content (be cautious when deleting).

Move to Recycle Bin (AliYun Drive)

Long-press a file in the AliYun Drive file source to move the folder/file to the recycle bin. Items in the recycle bin can be viewed in AliYun Drive and restored from there.

Multiple File Operations

1.When entering the file source page and selecting a folder, you can view all video files within it. Click the three dots in the upper right corner and then select "Edit".
From there, you can also click "Rescan Files (Current Directory)" to perform a file scan.

2.After clicking "Edit", all pages will enter an editable state.

3.After selecting one or multiple files, click the three dots in the lower right corner to perform operations on the selected files. Once you are done with the operations, click "Done" in the upper right corner to complete.

1.When watching a video, unfinished videos will be categorized under "Continue Watching" and display the progress. Simply click the white play button to continue watching.
2.For movies, once you finish watching, they will be categorized under "Watched" section.
3.For TV shows, after finishing the current episode, the next episode will be shown under "Continue Watching". In the case of multiple seasons, after finishing a season, the first episode of the next season will be displayed. Once you have finished watching all seasons, it will be categorized under "Watched" section.

4.Long-pressing a video in the "Continue Watching" category allows you to "Mark as Watched."

5.There are three options for marking as watched:
5.1. Current Episode: Selecting this option will move the current episode to the "Watched" category.
5.2. Full Season: Choosing this option will move all episodes within a season to the "Watched" category.
For example: If Season 1 is marked as watched, Season 2 will appear under "Continue Watching."
5.3. Full Series: Opting for this option will move the entire series to the "Watched" category.
For example: All seasons and episodes will be marked as watched, and they will not appear in "Continue Watching."

Add Playlist

1.To create your own playlist, click on the three dots in the top right corner of the homepage, then select "Edit Media Library."
2.Scroll down to find the playlist and check the box (it is not displayed by default).

3.In the media library, find the playlist and click "View All."

4.On the "All Playlists" page, click on "Create New Playlist" in the top right corner.

5.Name the new playlist and click "Save" to create it.
6.After saving, the newly added playlist will be displayed on the playlists page.

To delete a playlist

1.Enter the playlist you wish to delete, then click on the three dots in the top right corner, and select "Delete Playlist."
Note: Deleting a playlist will only remove the playlist. The videos can still be found in the media library.

Adding videos to playlists

If you want to add a video to a playlist, long-press on the movie poster on the media library page, then click on "Add to Playlist."
Note: If adding a TV series to a playlist, all videos within the series will be added to the playlist.

Adding to Favorites

Long-press on the movie poster, click on "Add to Favorites," and the movie will be displayed in the Favorites category. Long-press again and click "Remove from Favorites" to remove it from the Favorites.
Note: The Favorites category will only be visible when selected for display, otherwise it won't show. (Settings can be adjusted in the media library - top right corner three dots - Edit media library.)

Mark as Watched

Movies marked as watched will be categorized as such. Unmarking them will remove them from the category.
Note: If a movie in the "Continue Watching" category is marked as watched, even if unmarked, the previous viewing record will remain.

Media Library Status Information

When scanning files, scroll to the bottom to view the current scanning status. Upon completion, the total number of movies/TV shows/other videos in the media library will be displayed at the bottom.

Media Library

Media Library: All the displayed movies are sourced from the video files in the "File Sources" section. When you add a new folder as a file source, VidHub will automatically search, scrape, and add all the video files in that source to the media library.
Definition: Scraping refers to searching online for movie/show information and posters based on the video file names, and then adding the search results to the media library after organizing them.
Clicking on the three-dot icon in the top right corner will present options: "Rescan Files" and "Edit Media Library".
1.2: "Rescan Files" does exactly as its name implies. It rescans all video files in the file sources, identifies any changes, and synchronizes them with the media library. It is necessary to rescan files when there are changes (additions/deletions/renaming) in the videos within the file sources.
(For users with a large number of movies in their file sources, be cautious when using this feature as it performs a full scan of all file sources, which may take a considerable amount of time. If you know the precise location of the newly added/deleted/renamed video files, it is recommended to scan only that specific location, which will be explained later.)
1.3: "Edit Media Library" allows you to "show/hide/sort" categories within the media library. For example, you can choose to hide the movie category, so it will no longer be visible. You can also rearrange the order of the categories, such as moving TV shows to the second position and movies to the first position.
1.4: Clicking on "View All" shows all the movies within the current category.

File Sources

File Sources can be understood as a repository, a place to manage movie resources. It supports adding, deleting, disabling, renaming, and rescanning files.
Definition: It is a repository for storing movies.
Long-press on any added file source.
1.2: Delete: Delete the file source. All related movies in the media library will be automatically removed after deletion.
1.3: Disable/Enable: Clicking on "Disable" will hide all related movies in the media library. Clicking on "Enable" will display all related movies in the media library again.
1.4: Rename: As the name suggests, modify the name of the "File Source".
1.5: Rescan Files: Perform a separate scan for the files in this file source. It will not affect other file sources.

1.6: The naming convention in the top-left corner of the File Sources section is where you can specify the naming format for movies/shows. Only when you follow the convention and name your movies/shows accordingly, will VidHub automatically scan and gather the corresponding movie/show information, and organize them in the media library.
1.7: Edit: By clicking on the three-dot icon in the top-right corner and selecting "Edit," you can choose multiple file sources and delete them.
1.8: Add/Modify File Source: By clicking on the three-dot icon in the top-right corner, the option to "Add/Modify File Source" will appear.

1.9: Click on "Add/Modify File Source" to access the current page (which stores added local/network/cloud sources).
2.0: Click on "Add Storage" for redirection.
2.1: Network Share: Input the "Server Address" (URL), Port, Username, Password, Path (optional) (from shared by others or if you have your own storage URL videos, assuming VidHub supports it; currently supports WebDav and SMB protocols).
2.2: Cloud Drive: Import movies from the cloud drive to VidHub for organization and playback. For details, please refer to the beginner's guide. Currently supports Alibaba Cloud Drive/Baidu Cloud Drive/Dropbox/OneDrive/Google Drive/Premiumize, etc.

2.3: Open Local Videos: Upon clicking this option, an iCloud Drive pop-up will appear. If the video resources are stored in iCloud, you can directly navigate to the corresponding folder and play the selected video.
If the videos are not in iCloud, click the top-left corner to return to browsing. In the Location category, find and click on "My iPhone." From there, navigate to the folder where the video resources are stored and click to enter. You can then directly play the video files.
Note: Opening local videos will directly play the selected video file.
2.4: Add Local Directory: Select a local folder as a file source. Upon clicking, an iCloud Drive pop-up will appear. If the resources are located in iCloud, you can directly navigate to the corresponding folder. Click "Open" in the top-right corner to add this directory as a file source.
If the resources are not in iCloud, click on the top-left corner to return to browsing. Look for "My iPhone" in the Location category and click on it. Browse through the files on your iPhone to find the folder where the video resources are stored. Once inside the folder, click "Open" in the top-right corner to add this directory as a file source.
Note: The selected local directory will be added as a file source, and all video files within that directory will be scraped and imported into the media library.
If your local videos are in the Photo app, you need to long-press the video, click on "Share," and then choose "Save to Files." Afterwards, you can use the Open Local Video/Open Local Directory features in VidHub to play or import the video into the media library.

Media Servers

Media Servers: VidHub supports adding Plex/Emby/Jellyfin media servers. By providing the server address, username, password, and other required information, you can log in and add a media server. Once added successfully, you can access and stream content from the media server by clicking on it. (Media servers can be self-hosted or publicly accessible servers set up by others.)

VidHub is a versatile video player for iPhone, iPad, Apple TV, and Mac. When you need a feature-rich media player to manage, organize, and play various types of videos, VidHub will meet your needs.
VidHub supports managing video files on Aliyun Disk/Baidu Cloud/Google Drive/Dropbox/One Drive, supports samba(smb)/webdav protocols, supports NAS network storage such as Synology, supports local files, and supports Plex/Emby/Jellyfin media servers.
VidHub can automatically scrape movie/show covers and other information based on video file names, automatically categorize and organize your video resources, and support one-click global search. It also has powerful and user-friendly playback features, including playback speed adjustment, subtitles, screenshots, HDR, Dolby Vision, and more.

What media formats are supported

VidHub can support a wide range of video playback files
video：mkv、mp4、mov、rmvb、rm、avi、webm、wmv、mpeg etc.
Subtitles: VidHub supports built-in subtitles in videos and can mount a variety of external subtitle formats, such as SRT, SSA, ASS, SUB.

Best Compatible Devices for VidHub

Mac
Device requires macOS 10.15 or later.
iPhone
Device requires iOS 14.1 or later.
iPad
Device requires iPadOS 14.1 or later.
iPod touch
Device requires iOS 14.1 or later.
Apple Vision
Device requires VisionOS 1.0 or later.
Apple TV
Device requires Apple tvOS 14.0 or later.

What else can VidHub do for me?

VidHub offers excellent file management capabilities and supports interface display of video playlists. Users can quickly find the desired media files by categorizing them based on types, dates, ratings, and more.
But it doesn't stop there. VidHub has many powerful features waiting for you to explore. We are continuously striving to improve the user experience, and we greatly appreciate your valuable suggestions and feedback. Please feel free to share your thoughts with us through the community, App Store, or email. Thank you.