MediaBot User Guide

Welcome to MediaBot, your lightweight, privacy-focused media server designed for completely offline use. This guide will help you navigate and use the MediaBot web interface efficiently.

MediaBot allows you to organize, stream, and enjoy your personal media collection including movies, TV shows, music from anywhere on your home network without requiring an internet connection.

Quick Start

For those in a hurry, here's the short rundown on how to get started

1. Download and install MediaBot Server from the Apple App Store
2. Start the app, the MediaBot Icon will appear in your menu bar at the top right of your screen
3. Click the Icon and select "Open MediaBot...". Your browser will open to the MediaBot's web interface in Safari
4. You should be on the configuration page. A default user "admin" with password "admin" is already created.
5. Click the "Edit" icon next to the "admin" user and enter a new password. Click "Save"
6. Click the "Edit" icon next to the "Movies" library
7. Click "Grant Folder Access" and select the folder containing your movie collection (i.e. Movies)
We recommend creating a Media folder in your home directory or the root of your hard drive and creating subdirectories in it such as Movies. You can also put it on an external USB/SSD drive.
8. Click the dropdown for Path and select the folder you created
9. You can add more than one path for your library
10. Click "Save"
11. Click "Scan" to start indexing your movie collection
12. Select "Movies" from the menu bar and select a movie to start watching

Features

MediaBot provides a comprehensive set of features for managing and enjoying your media:

• Multiple Media Types - Support for videos and music
• Library Management - Create and organize libraries for different media types
• Media Playback - Built-in players for videos and music with resume and shuffle support
• Drag-and-Drop Uploads - Upload media files directly to your libraries
• Playlists - Create and manage playlists for your media
• User Management - Create accounts with four granular access levels per library
• Replica Libraries - Mirror libraries from remote MediaBot servers to your local machine
• Scheduled Jobs - Run shell commands automatically on a cron schedule
• Encoding - Convert media files using built-in encoding profiles
• Offline Access - Works entirely on your local network with no internet required
• Cross-Browser Support - Access from any modern web browser
• Privacy-Focused - No tracking or data collection

Media Libraries

Libraries are the foundation of MediaBot. They organize your media by type and location.

Library Types

• Movies - For your movie collection (supports MP4, M4V, MOV)
• TV Shows - For television series (supports MP4, M4V, MOV)
• Music - For audio files (supports MP3, M4A, AAC)

Creating a Library

1. Navigate to the Libraries section in the main menu
2. Click "Add Library"
3. Enter a name for your library
4. Select the library type
5. Click "Pick Folder" to select the folder containing your media
6. Click "Save" to create the library
7. Click "Scan" to index the media in your library

Managing Libraries

From the Libraries section, you can:

• Edit library details
• Scan libraries to update their content
• Delete libraries
• Manage user access to libraries

Media Playback

MediaBot includes built-in players for various media types.

Video Playback

To play a video:

1. Navigate to a Movies or TV library
2. Click on a video thumbnail to start playback
3. Use the on-screen controls to play, pause, seek, and adjust volume
4. Click the forward/backward buttons to navigate between videos
5. Toggle shuffle mode with the shuffle button

MediaBot remembers your playback position for videos, allowing you to resume where you left off.

Music Playback

To play music:

1. Navigate to a Music library
2. Click on a song to start playback
3. Use the audio player controls to play, pause, and navigate between tracks
4. Toggle shuffle mode with the shuffle button

Playlists

Playlists allow you to organize and play selected media in a specific order.

Creating a Playlist

1. Navigate to the Playlists section
2. Click "Add Playlist"
3. Enter a name for your playlist
4. Click "Save"

Adding Media to a Playlist

1. Navigate to a media library
2. Find the media item you want to add
3. Click the menu icon on the media item
4. Select "Add to Playlist"
5. Choose the playlist you want to add the item to

Playing a Playlist

1. Navigate to the Playlists section
2. Click on the playlist you want to play
3. Click on a media item to start playback
4. The playlist will continue playing in sequence

User Management

MediaBot supports multiple user accounts with different access levels.

User Roles

Each user is assigned a role per library, controlling what they can do:

• Admin - Full access including adding users and deleting the library
• Full - Full access including deleting files, but cannot add users or delete the library
• Edit - Can edit media items but cannot delete
• View - Read-only access to the library

Creating a User

1. Navigate to the Users section (admin access required)
2. Click "Add User"
3. Enter a username and password
4. Click "Save"

Managing Library Access

1. Navigate to the Libraries section
2. Select a library
3. Click "Manage Access"
4. Select which users can access the library
5. Click "Save"

Scheduled Jobs (Cronjobs)

Scheduled Jobs let you run shell commands automatically on a cron schedule.

1. Go to the Libraries page and find the Scheduled Jobs section (admin only).
2. Click the plus icon to create a job.
3. Fill in Command, optional Arguments, optional Working folder, and Schedule (cron format).
4. Set Timeout in minutes (0 means no timeout) and enable the job.
5. Use Run now to start immediately, Stop to cancel a running job, and Log to view output.

Tip: The log view supports live output while a job is running.

Cron format tip: MediaBot uses standard 5-field cron format (minute hour day-of-month month day-of-week) and does not use a leading seconds field. If you are unsure about syntax, see Crontab Guru for quick examples and explanations.

Encoding

Encoding creates converted versions of media files using predefined encoding profiles.

1. Open a media library and open the menu on a media item.
2. Select Encode and choose a profile.
3. The job is added to the Encoding Queue on the Libraries page.
4. Queue items show status: queued, encoding, completed, or error.
5. You can cancel queued/running jobs, retry failed jobs, and remove completed/error jobs from the queue.

Note: The Encode menu is shown only when encoding profiles are available.

Replica Libraries

Replica libraries let you mirror a library from a remote MediaBot server onto your local machine. This is useful for keeping a secondary copy of your media in sync, or for consolidating content from multiple MediaBot installations.

Setting Up a Replica Source

1. Navigate to the Libraries page and find the Replica Sources section (admin only).
2. Click the plus icon to add a new source.
3. Enter a name, the URL of the remote MediaBot server, and the username and password for that server.
4. Click Test to verify the connection and fetch the list of available remote libraries.
5. Click Save.

Creating a Replica Library

1. Create a new library (or edit an existing one) of the same type as the remote library.
2. In the library edit page, enable Replica and select the replica source and remote library you want to mirror.
3. Choose a local library path where downloaded files will be stored.
4. Click Save, then click Sync to start the initial synchronisation.

MediaBot performs a full sync on first run and incremental syncs thereafter, downloading only new or changed files.

Upload Files to Libraries

You can upload media files directly to a library by dragging files into the page.

1. Open the library you want to upload to (for example Movies or Music).
2. Drag one or more files from your computer and drop them anywhere on the media page.
3. When the drop overlay appears, release the files to start upload.
4. Wait for the upload progress indicator to reach 100%.
5. MediaBot refreshes the library view automatically after upload.

Tip: Large uploads may take time depending on your network and file size.

Grant Folder Access

MediaBot does not have access to any of your folders. Before it can access any Media, you must grant it access to the folders containing your media. It does not have access to browse your folders unless you grant it access to root of your drive. We therefore recommend you put your media in a Media folder in your home directory or the root of your hard drive and create subdirectories in it such as Movies, TV Shows, Music, etc. The best and most common setup is to use a USB/SSD drive for all your media and grant MediaBot access to that drive.

Host MediaBot with Cloudflare Zero Trust

If you want to reach MediaBot from outside your home network without opening router ports, use Cloudflare Zero Trust with a Cloudflare Tunnel.

1. Create a Cloudflare account and open the Zero Trust dashboard.
2. Create a Tunnel and install cloudflared on the machine running MediaBot.
3. Add a public hostname in the tunnel (for example media.example.com) and point it to your local MediaBot address (for example http://localhost:8080).
4. Create a Self-hosted application in Zero Trust for that hostname.
5. Add an Access policy so only approved users can sign in.
6. Open your public hostname and confirm you see the Cloudflare login screen before MediaBot loads.

Official Cloudflare docs: Create a Tunnel, Self-hosted applications, Access policies.

Frequently Asked Questions

Does MediaBot require an internet connection?

No, MediaBot is designed to work completely offline on your local network. Once installed, you can access and use it without any internet connection.

What file formats are supported?

MediaBot supports file formats that play natively in Safari:

• Video: MP4, M4V, MOV
• Audio: MP3, M4A, AAC

How do I update MediaBot?

MediaBot updates are distributed through the App Store. When a new version is available, you'll receive a notification through the App Store, and you can update with a single click.

Is my media collection secure?

Yes, MediaBot is designed with privacy and security in mind. Your media stays on your local network, and MediaBot doesn't collect any usage data or personal information.

Can I access MediaBot from outside my home network?

MediaBot is designed for local network use. If you need remote access, you would need to set up a VPN to your home network.

Support

If you need help with MediaBot, there are several ways to get support:

Contact Information

For direct support, contact us at: team@mediabot.net

Reporting Issues

If you encounter any bugs or issues, please include the following information:

• MediaBot version
• Device and browser information
• Detailed description of the issue
• Steps to reproduce the issue
• Screenshots (if applicable)

Feature Requests

We're always looking to improve MediaBot. If you have suggestions for new features or improvements, please let us know at the email address above.