bybrooklyn/tunarr
1
0
Fork 0
mirror of https://github.com/chrisbenincasa/tunarr.git synced 2026-04-18 09:03:35 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: add section about local music library scanning

Browse Source 
organizes index pages with cards
This commit is contained in:
Christian Benincasa
2026-01-18 10:10:05 -05:00
parent ec4780725c
commit 3438564e80
16 changed files with 946 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/configure/channels/index.md
View File

@@ -1,9 +1,54 @@
# Channels
This page will display a brief overview of your channels.
Channels are the core of Tunarr. Each channel acts like a virtual TV station with its own programming schedule, stream settings, and EPG data.
Click the "NEW" button to be brought to the [New Channel Properties](/configure/channels/properties) page.
![Creating a new channel](../../assets/channels-new.png)
![Creating a new channel](/assets/channels-new.png)
Click the **NEW** button to create your first channel, which will take you to the [Channel Properties](properties.md) page.
Once you have created your first channel, head over to [Programming](/configure/programming) to start adding episodes.
<div class="grid cards" markdown>
- **[Properties](properties.md)**
---
Configure basic channel settings like name, number, icon, and group.
- **[Programming](programming.md)**
---
Add shows, movies, and other content to your channel's schedule.
- **[Flex](flex.md)**
---
Configure filler content to play during gaps in your schedule.
- **[EPG](epg.md)**
---
Customize how your channel appears in electronic program guides.
- **[Transcoding](transcoding.md)**
---
Configure stream modes and transcoding settings per channel.
- **[Watermarks](watermarks.md)**
---
Add logo overlays and watermarks to your channel's video output.
</div>
## Getting Started
1. Create a new channel with [Properties](properties.md)
2. Add content via [Programming](programming.md)
3. Use [Scheduling Tools](../scheduling/index.md) to organize your lineup
4. Configure a [Client](../clients/index.md) to watch your channel

43
docs/configure/clients/index.md
View File

@@ -1,3 +1,44 @@
# Clients
Once you have your channels created within Tunarr, you are ready to configure your clients. We currently have a guide written for [Plex](/configure/clients/plex), but [Jellyfin](/configure/clients/jellyfin) and Emby should work as well. You can also utilize generated M3U files with any 3rd party IPTV player app. We recommend [UHF](https://www.uhfapp.com/) for iOS or [Tivimate](https://tivimate.com/) for Android TV.
Once you have your channels created in Tunarr, you're ready to watch them! Tunarr works with a variety of clients through its HDHomeRun emulation and M3U playlist support.
<div class="grid cards" markdown>
- **[Plex](plex.md)**
---
Add Tunarr as an HDHomeRun tuner in Plex to watch channels with full DVR integration.
- **[Jellyfin](jellyfin.md)**
---
Configure Jellyfin to use Tunarr channels via HDHomeRun or M3U.
</div>
## Other Clients
Tunarr generates M3U playlists that work with any IPTV player. Some recommended apps:
| Platform | App |
|----------|-----|
| iOS / Apple TV | [UHF](https://www.uhfapp.com/) |
| Android TV | [TiviMate](https://tivimate.com/) |
| Cross-platform | [VLC](https://www.videolan.org/vlc/) |
## Connection Methods
Tunarr supports two ways to connect clients:
### HDHomeRun Emulation
Tunarr emulates an HDHomeRun network tuner, allowing media servers like Plex, Jellyfin, and Emby to discover it automatically. This provides the most seamless integration with full guide data.
### M3U Playlists
For IPTV apps and other players, Tunarr generates M3U playlist files. Access them at:
- **All channels**: `http://your-tunarr-ip:8000/api/channels/m3u`
- **XMLTV guide**: `http://your-tunarr-ip:8000/api/xmltv`

32
docs/configure/library/index.md
View File

@@ -1,5 +1,33 @@
# Library
[Filler](/configure/library/filler) lists are collections of videos that you may want to play during [Flex](/configure/channels/flex) time segments. Flex is time within a channel that does not have a program scheduled (usually used for padding).
The Library contains reusable collections of content that can be used across multiple channels. This includes filler content for gaps in your schedule and custom shows that group videos together.
[Custom Shows](/configure/library/custom-shows) are sequences of videos that represent a episodes of a virtual TV show. When you add these shows to a channel, the schedule tools will treat the videos as if they belonged to a single TV show.
<div class="grid cards" markdown>
- **[Filler](filler.md)**
---
Collections of videos to play during [Flex](../channels/flex.md) time segments, such as commercials, bumpers, or interstitials.
- **[Custom Shows](custom-shows.md)**
---
Create virtual TV shows by grouping videos into episodes. Scheduling tools will treat these as a single show.
- **[Smart Collections](smart-collections.md)**
---
Dynamic collections that automatically include content matching specified criteria.
</div>
## When to Use Each
| Feature | Use Case |
|---------|----------|
| **Filler** | Commercials, station IDs, bumpers, short clips to fill gaps |
| **Custom Shows** | YouTube series, home videos, or any content you want to treat as episodic |
| **Smart Collections** | Auto-updating playlists based on genre, year, rating, etc. |

3
docs/configure/media_sources/emby.md
View File

@@ -0,0 +1,3 @@
# Emby
Emby instructions coming soon! For now, they are very similar to the Jellyfin instructions, so that can be used as a reference.

41
docs/configure/media_sources/index.md
View File

@@ -1,3 +1,42 @@
# Media Sources
Tunarr finds media to use in channels from one or more "Media Sources". Tunarr supports [Plex](./plex.md), [Jellyfin](./jellyfin.md), and [Emby](./emby.md) as Media Sources. In alpha versions, Tunarr also supports [Local](./local.md) Media Sources.
Tunarr finds media to use in channels from one or more "Media Sources". You can connect multiple media servers and use content from any of them when building your channels.
<div class="grid cards" markdown>
- **[Plex](plex.md)**
---
Connect your Plex Media Server to access your movies, TV shows, and other media.
- **[Jellyfin](jellyfin.md)**
---
Connect your Jellyfin server to use its media libraries in your channels.
- **[Emby](emby.md)**
---
Connect your Emby server to access its media content.
- **[Local Media](local/index.md)**
---
Use media files directly from your local filesystem without a media server.
</div>
## How Media Sources Work
When you add a media source, Tunarr will scan its libraries and index the available content. This allows you to:
- Browse and search media when adding programming to channels
- Automatically detect metadata like titles, episode numbers, and artwork
- Keep your channel programming in sync when media is added or removed
!!! tip
You can add multiple media sources of the same type. For example, you could connect two different Plex servers and use content from both.

20
docs/configure/media_sources/jellyfin.md
View File

@@ -63,25 +63,7 @@ When using external Media Sources, it is recommended to ensure Tunarr has access
Option 1 is simpler and requires no additional configuration within Tunarr.
### Configuring Path Replacements (stable)
On current stable versions path replacements can only be configured once for all servers, globally.
First change the "Stream Path" mode to "Direct"
<figure markdown="span">
![](../../assets/media_source_direct_path.png)
<figcaption>Direct stream path mode</figcaption>
</figure>
Then, configure your stream path. Tunarr uses prefix-matching for the "original" path to replace.
<figure markdown="span">
![](../../assets/media_source_path_replacement_old.png)
</figure>
### Configuring Path Replacements (alpha)
### Configuring Path Replacements
!!! info
Alpha versions allow configuring path replacements per-media-source.

70
docs/configure/media_sources/local/index.md
View File

@@ -2,21 +2,71 @@
status: new
---
# Local
# Local Media
!!! info
This feature is only available on alpha builds! It will be released as part of Tunarr 1.0.
Local Media Sources allow scheduling media from your filesystem without requiring a media server like Plex or Jellyfin.
Local Media Sources allow scheduling media from your filesystem (i.e. no media server is necessary).
Tunarr traverses folders to discover metadata and media files which can then be scheduled to channels.
Tunarr traverses folders for Local Media Sources to discover metadata and media files which can then be scheduled to channels.
<div class="grid cards" markdown>
Currently, Tunarr supports the following media types for Local sources:
- **[Movies](movies.md)**
1. [Movies](/configure/media_sources/local/movies)
2. Shows
3. "Other" Videos (unstructured)
---
Add movie files with NFO metadata support.
- **[Shows](shows.md)**
---
Add TV series with episode organization and NFO metadata.
- **[Other Videos](other_videos.md)**
---
Add unstructured video files without specific metadata requirements.
- **[Music](music.md)**
---
Add music libraries with artist/album organization and embedded metadata support.
</div>
## Generating Metadata
There are many ways to generate NFO files for consumption by Tunarr if your media does not already have them. Popular *arr stack programs, Jellyfin, and Emby all support writing out NFO files for media.
There are many ways to generate NFO files for consumption by Tunarr if your media does not already have them. Popular *arr stack programs, Jellyfin, and Emby all support writing out NFO files for media.
## Folder Structure
For best results, organize your media following standard conventions:
**Movies:**
```
/movies/
Movie Name (2024)/
Movie Name (2024).mkv
Movie Name (2024).nfo
```
**TV Shows:**
```
/shows/
Show Name/
Season 01/
Show Name - S01E01 - Episode Title.mkv
Show Name - S01E01 - Episode Title.nfo
```
**Music:**
```
/music/
Artist Name/
artist.nfo
Album Name (2024)/
album.nfo
01 - Track Title.flac
```

107
docs/configure/media_sources/local/music.md Normal file
View File

@@ -0,0 +1,107 @@
# Music
## Library Structure
Local Music libraries expect a hierarchical structure with artist folders at the top level and album folders nested within each artist. Track files are scanned from within album folders.
```
music/
|
├ Billy Joel/
| ├ artist.nfo
| ├ folder.jpg
| ├ Greatest Hits Volume I & II (1985)/
| | ├ album.nfo
| | ├ folder.jpg
| | ├ 01 - Piano Man.flac
| | └ 02 - The Entertainer.flac
| |
| └ The Stranger (1977)/
| ├ album.nfo
| ├ 01 - Movin' Out.mp3
| └ 02 - The Stranger.mp3
|
├ The Beatles/
| ├ artist.nfo
| └ Abbey Road (1969)/
| ├ album.nfo
| └ 01 - Come Together.m4a
|
```
## Supported Audio Formats
Tunarr supports the following audio file formats:
`.aac`, `.aif`, `.aifc`, `.aiff`, `.alac`, `.dff`, `.dsf`, `.flac`, `.mp3`, `.m4a`, `.ogg`, `.opus`, `.oga`, `.ogx`, `.spx`, `.wav`, `.wma`
## Metadata
Tunarr supports NFO files for both artists and albums. These follow conventions similar to those used by Kodi and other media managers.
### Artist Metadata
For each artist folder, Tunarr will look for an NFO file called `artist.nfo`. Supported fields include:
- `name` - Artist name
- `sortname` - Name used for sorting (e.g., "Joel, Billy")
- `musicBrainzArtistID` - MusicBrainz artist identifier
- `genre` - One or more genre tags
- `style` - One or more style tags
- `mood` - One or more mood tags
- `born` - Birth date (for solo artists)
- `formed` - Formation year (for bands)
- `biography` - Artist biography
### Album Metadata
For each album folder, Tunarr will look for an NFO file called `album.nfo`. Supported fields include:
- `title` - Album title
- `musicbrainzalbumid` - MusicBrainz album identifier
- `musicbrainzreleasegroupid` - MusicBrainz release group identifier
- `genre` - One or more genre tags
- `style` - One or more style tags
- `mood` - One or more mood tags
- `theme` - One or more theme tags
- `releasedate` - Release date
- `originalreleasedate` - Original release date
- `label` - Record label
- `compilation` - Whether the album is a compilation
- `boxset` - Whether the album is part of a boxset
- `albumArtistCredits` - Artist information including MusicBrainz ID
### Song Metadata
Tunarr reads native tags for a huge variety of music formats, including MP3, MP4, FLAC, Ogg, WAV, AIFF, and can read many metadata formats, including ID3v1, ID3v2, APE, Vorbis, and iTunes/MP4 tags. Some of the metadata extracted from individual music files, such as genre, are also retroactively applied to the parent album.
## Artwork
Tunarr will attempt to scan various artwork files for artists and albums.
**Artist artwork:**
- Poster: `poster.*` or `folder.*`
- Fanart: `fanart.*`
- Banner: `banner.*`
**Album artwork:**
- Poster: `poster.*` or `folder.*`
## Fallback
Without NFO files, Tunarr will extract metadata from embedded audio tags (ID3, Vorbis comments, etc.) using the track files themselves. This includes:
- Track title
- Track number
- Year and release date
- Genres (split on `;`, `,`, or `|` delimiters)
For artist and album names, Tunarr will use the folder name. Album folder names may include a year in parentheses (e.g., "Album Name (2024)") which Tunarr will parse automatically.
Tracks without a title or track number in their embedded metadata will be skipped during scanning.
## Ignoring Folders
To exclude specific folders from scanning, create an empty file named `.tunarrignore` in any folder you wish to skip. Folders and files starting with `.` are also ignored automatically.

19
docs/configure/media_sources/plex.md
View File

@@ -46,24 +46,7 @@ When using external Media Sources, it is recommended to ensure Tunarr has access
Option 1 is simpler and requires no additional configuration within Tunarr.
### Configuring Path Replacements (stable)
On current stable versions path replacements can only be configured once for all servers, globally.
First change the "Stream Path" mode to "Direct"
<figure markdown="span">
![](../../assets/media_source_direct_path.png)
<figcaption>Direct stream path mode</figcaption>
</figure>
Then, configure your stream path. Tunarr uses prefix-matching for the "original" path to replace.
<figure markdown="span">
![](../../assets/media_source_path_replacement_old.png)
</figure>
### Configuring Path Replacements (alpha)
### Configuring Path Replacements
!!! info
Alpha versions allow configuring path replacements per-media-source.

59
docs/configure/scheduling/index.md
View File

@@ -1,17 +1,60 @@
# Scheduling Tools
Tunarr offers a range of tools for modifying channel schedules. However, it is important to first become familiar with Tunarr's scheduling [concepts](./concepts.md).
Tunarr offers a range of tools for modifying channel schedules. Before diving in, familiarize yourself with Tunarr's scheduling [concepts](concepts.md).
* [Slot Editor](random-slots.md) allows assigning programming to "slots" of fixed or dynamic duration. Slots can then be played back sequentially or at random when generating a schedule.
<div class="grid cards" markdown>
* [Time Slots](time-slots.md) mimic traditional TV scheduling, where programs are assigned to a particular start time and duration.
- **[Concepts](concepts.md)**
* [Block Shuffle](block-shuffle.md) is a simpler version of slot editor. Randomly chooses "blocks" of programming of a chosen size.
---
* [Cyclic Shuffle](cyclic-shuffle.md)
Understand how Tunarr's scheduling system works before using the tools.
* [Balance](balance.md) lets you pick the weight for your shows to air some shows more frequently than others.
- **[Slot Editor](random-slots.md)**
* [Replicate](replicate.md) will create copies of the same schedule and play them in sequence. This typically is not needed as Tunarr already handles replaying a schedule once complete. Some use this as an intermediate tool before applying other tools, like balance.
---
* [Consolidate](consolidate.md) merges contiguous match flex and redirect blocks into singular spans.
Assign programming to "slots" of fixed or dynamic duration, played sequentially or randomly.
- **[Time Slots](time-slots.md)**
---
Traditional TV scheduling where programs are assigned to specific start times.
- **[Block Shuffle](block-shuffle.md)**
---
Simpler version of slot editor that randomly chooses "blocks" of programming.
- **[Cyclic Shuffle](cyclic-shuffle.md)**
---
Cycle through programming in a repeating pattern.
- **[Replicate](replicate.md)**
---
Create copies of a schedule to play in sequence. Useful as an intermediate step.
- **[Consolidate](consolidate.md)**
---
Merge contiguous flex and redirect blocks into single spans.
</div>
## Choosing a Tool
| Goal | Recommended Tool |
|------|------------------|
| Mimic traditional TV with set air times | [Time Slots](time-slots.md) |
| Random variety with control over duration | [Slot Editor](random-slots.md) |
| Simple random playback | [Block Shuffle](block-shuffle.md) |
| Predictable rotation through content | [Cyclic Shuffle](cyclic-shuffle.md) |
| Extend a schedule before applying other tools | [Replicate](replicate.md) |
| Clean up fragmented flex time | [Consolidate](consolidate.md) |

189
docs/configure/system/backup.md Normal file
View File

@@ -0,0 +1,189 @@
# Backup & Restore
Tunarr provides a backup system that creates compressed archives of your configuration, database, and media assets. Backups can be scheduled to run automatically or triggered manually.
## What Gets Backed Up
A Tunarr backup archive includes:
| Item | Description |
|------|-------------|
| `db.db` | SQLite database containing channels, programs, and configuration |
| `settings.json` | System settings and media source configurations |
| `channel-lineups/` | Channel lineup data and M3U files |
| `images/` | Channel logos, artwork, and thumbnails |
| `cache/` | Cached subtitles, posters, banners, fanart, and watermarks |
| `ms-snapshots/` | Meilisearch index snapshots (optional) |
| `*.xml` | XMLTV output files |
## Configuration
Backup settings can be configured in the Tunarr web UI under **Settings > System > Backup**, or via the API.
### Backup Options
| Option | Default | Description |
|--------|---------|-------------|
| **Enabled** | `true` | Enable or disable scheduled backups |
| **Schedule** | Daily at 4:00 AM | When to run automatic backups |
| **Output Path** | `{data directory}/backups/` | Where backup files are stored |
| **Archive Format** | `tar` | Archive format: `tar` or `zip` |
| **Gzip Compression** | `false` | Enable gzip compression (tar only) |
| **Max Backups** | `3` | Number of backups to retain before deleting oldest |
### File Naming
Backup files are named using a timestamp format:
```
tunarr-backup-YYYYMMDD_HHmmss.tar
tunarr-backup-YYYYMMDD_HHmmss.tar.gz (with gzip)
tunarr-backup-YYYYMMDD_HHmmss.zip
```
Example: `tunarr-backup-20250118_040000.tar.gz`
## Scheduling
Backups can be scheduled in two ways:
### Interval-Based
Run backups at regular intervals:
- Every N hours
- Every N days
Example: "Every 1 day at 4:00 AM"
### Cron-Based
Use a cron expression for more complex schedules:
```
0 4 * * * # Daily at 4:00 AM
0 */6 * * * # Every 6 hours
0 4 * * 0 # Weekly on Sunday at 4:00 AM
```
## Manual Backup
### Via Web UI
Navigate to **Settings > System > Backup** and click the **Backup Now** button.
### Via API
Trigger a backup using the tasks API:
```bash
curl -X POST "http://localhost:8000/api/tasks/BackupTask/run"
```
To run the backup in the background (recommended for large installations):
```bash
curl -X POST "http://localhost:8000/api/tasks/BackupTask/run?background=true"
```
## Backup Retention
When a new backup is created and the total number of backups exceeds the `maxBackups` setting, the oldest backups are automatically deleted. This helps prevent disk space from filling up over time.
## Restore
!!! warning "Manual Process"
Tunarr does not currently have a built-in restore feature. Restoration must be done manually.
### Restore Steps
1. **Stop Tunarr** - Ensure the Tunarr server is not running
2. **Locate your data directory**:
- **Docker**: The path you mounted to `/config/tunarr`
- **Windows**: `%APPDATA%\tunarr`
- **macOS**: `~/Library/Preferences/tunarr`
- **Linux**: `~/.local/share/tunarr`
3. **Extract the backup archive**:
```bash
# For tar archives
tar -xvf tunarr-backup-YYYYMMDD_HHmmss.tar -C /path/to/restore/
# For gzipped tar archives
tar -xzvf tunarr-backup-YYYYMMDD_HHmmss.tar.gz -C /path/to/restore/
# For zip archives
unzip tunarr-backup-YYYYMMDD_HHmmss.zip -d /path/to/restore/
```
4. **Copy files to the data directory**:
```bash
# Required files
cp /path/to/restore/db.db /path/to/tunarr/data/
cp /path/to/restore/settings.json /path/to/tunarr/data/
# Optional directories (restore as needed)
cp -r /path/to/restore/images/ /path/to/tunarr/data/
cp -r /path/to/restore/cache/ /path/to/tunarr/data/
cp -r /path/to/restore/channel-lineups/ /path/to/tunarr/data/
```
5. **Start Tunarr** - The search index will rebuild automatically if not restored
### Docker Restore Example
```bash
# Stop the container
docker stop tunarr
# Extract backup to a temporary location
tar -xzvf tunarr-backup-20250118_040000.tar.gz -C /tmp/tunarr-restore/
# Copy to your mounted volume
cp /tmp/tunarr-restore/db.db /path/to/tunarr/data/
cp /tmp/tunarr-restore/settings.json /path/to/tunarr/data/
# Start the container
docker start tunarr
```
## Excluding Search Snapshots
Meilisearch index snapshots can be large. To exclude them from backups, set the environment variable:
```bash
TUNARR_DISABLE_SEARCH_SNAPSHOT_IN_BACKUP=true
```
When restoring a backup without search snapshots, Tunarr will automatically rebuild the search index on startup. This may take a few minutes depending on your library size.
!!! warning "Windows Snapshots"
There is currently an [issue in Meilisearch](https://github.com/meilisearch/meilisearch/issues/6051) where snapshots do not work correctly on Windows. Until this is resolved, Windows users should disable Meilisearch snapshots.
## Backup Storage Locations
### Default Location
Backups are stored in the `backups/` subdirectory of your Tunarr data directory:
| Platform | Default Path |
|----------|--------------|
| Docker | `/config/tunarr/backups/` |
| Windows | `%APPDATA%\tunarr\backups\` |
| macOS | `~/Library/Preferences/tunarr/backups/` |
| Linux | `~/.local/share/tunarr/backups/` |
### Custom Location
You can configure a custom output path in the backup settings to store backups on a different drive or network location.
## Best Practices
1. **Test your backups** - Periodically verify that backups can be restored successfully
2. **Store backups off-site** - Copy backups to cloud storage or another machine
3. **Monitor disk space** - Ensure your backup location has sufficient free space
4. **Adjust retention** - Increase `maxBackups` if you need more recovery points
5. **Schedule during off-hours** - Run backups when Tunarr is less active to minimize impact

25
docs/configure/system/index.md
View File

@@ -1 +1,26 @@
# System
The System section covers Tunarr's core infrastructure settings including backup management, logging configuration, and other server-level options.
## Sections
<div class="grid cards" markdown>
- **[Backup & Restore](backup.md)**
---
Configure automatic backups, manage backup retention, and learn how to restore your Tunarr installation from a backup.
- **[Logging](logging.md)**
---
Configure log levels, log file rotation, and learn how to access logs for troubleshooting.
</div>
## Quick Links
- [Environment Variables](../../getting-started/run.md#configuration) - Server, logging, and search configuration via environment variables
- [FAQ](../../misc/faq.md) - Frequently asked questions including the Meilisearch `data.ms` file

273
docs/configure/system/logging.md Normal file
View File

@@ -0,0 +1,273 @@
# Logging
Tunarr provides configurable logging to help you monitor server activity and troubleshoot issues. Logs can be viewed in the console, written to files, and accessed via the web UI or API.
## Log Levels
Tunarr supports the following log levels, from least to most verbose:
| Level | Description |
|-------|-------------|
| `silent` | No logging output |
| `fatal` | Critical errors that cause the application to stop |
| `error` | Error conditions that should be investigated |
| `warn` | Warning conditions that may indicate problems |
| `info` | General operational information (default) |
| `debug` | Detailed information useful for debugging |
| `trace` | Very detailed trace information |
Additionally, Tunarr has custom levels for HTTP traffic:
| Level | Value | Description |
|-------|-------|-------------|
| `http` | 25 | Incoming HTTP request logging |
| `http_out` | 15 | Outgoing HTTP request logging (to Plex, Jellyfin, etc.) |
## Configuration
### Via Environment Variables
The simplest way to configure logging is through environment variables:
```bash
# Set log level (overrides UI setting)
LOG_LEVEL=debug
# Set custom log directory
LOG_DIRECTORY=/path/to/logs
```
### Via Web UI
Navigate to **Settings > System > Logging** to configure:
- Log level
- Log file directory
- Log rolling settings
### Via API
Update logging settings through the system settings API:
```bash
curl -X PUT "http://localhost:8000/api/system/settings" \
-H "Content-Type: application/json" \
-d '{
"logging": {
"logLevel": "debug",
"useEnvVarLevel": false,
"logRollConfig": {
"enabled": true,
"maxFileSizeBytes": 10485760,
"rolledFileLimit": 5
}
}
}'
```
## Log Files
### Location
Log files are stored in the `logs/` subdirectory of your Tunarr data directory:
| Platform | Default Path |
|----------|--------------|
| Docker | `/config/tunarr/logs/` |
| Windows | `%APPDATA%\tunarr\logs\` |
| macOS | `~/Library/Preferences/tunarr/logs/` |
| Linux | `~/.local/share/tunarr/logs/` |
### File Format
- **Main log file**: `tunarr.log`
- **Format**: NDJSON (newline-delimited JSON)
Each log entry contains:
```json
{"level":30,"time":1705574400000,"msg":"Server started","hostname":"tunarr","pid":1234}
```
## Log Rolling
Log rolling prevents log files from growing indefinitely by rotating them when they reach a certain size or on a schedule.
### Configuration Options
| Option | Default | Description |
|--------|---------|-------------|
| **Enabled** | `false` | Enable log file rotation |
| **Max File Size** | `1 MB` | Rotate when file exceeds this size |
| **Rolled File Limit** | `3` | Number of rotated files to keep |
| **Schedule** | (none) | Optional time-based rotation |
### Rotated File Naming
When rotation occurs:
1. `tunarr.log` is copied to `tunarr.log.1`
2. Existing numbered files shift up (`tunarr.log.1` → `tunarr.log.2`)
3. Files exceeding the limit are deleted
4. `tunarr.log` is truncated and continues receiving new entries
Example with `rolledFileLimit: 3`:
```
tunarr.log (current, active)
tunarr.log.1 (previous rotation)
tunarr.log.2 (older)
tunarr.log.3 (oldest, will be deleted on next rotation)
```
### Enabling Log Rolling
```bash
curl -X PUT "http://localhost:8000/api/system/settings" \
-H "Content-Type: application/json" \
-d '{
"logging": {
"logRollConfig": {
"enabled": true,
"maxFileSizeBytes": 10485760,
"rolledFileLimit": 5
}
}
}'
```
## Viewing Logs
### Via Web UI
Access logs in the Tunarr web interface under **Settings > System > Logs**.
### Via API
#### Stream Live Logs
Stream logs in real-time using Server-Sent Events:
```bash
# Raw NDJSON format
curl "http://localhost:8000/api/system/debug/logs/stream"
# Pretty-printed format
curl "http://localhost:8000/api/system/debug/logs/stream?pretty=true"
```
#### Download Logs
Download the log file:
```bash
# Download entire log file
curl "http://localhost:8000/api/system/debug/logs?download=true" -o tunarr.log
# Download last 1000 lines
curl "http://localhost:8000/api/system/debug/logs?download=true&lineLimit=1000" -o tunarr.log
# Download pretty-printed
curl "http://localhost:8000/api/system/debug/logs?download=true&pretty=true" -o tunarr.log
```
### Via Command Line
```bash
# Follow logs in real-time (Docker)
docker logs -f tunarr
# View log file directly
tail -f /path/to/tunarr/data/logs/tunarr.log
# Pretty-print JSON logs with jq
tail -f /path/to/tunarr/data/logs/tunarr.log | jq '.'
```
## Troubleshooting with Logs
### Recommended Log Levels
| Scenario | Recommended Level |
|----------|-------------------|
| Normal operation | `info` |
| Investigating issues | `debug` |
| Detailed troubleshooting | `trace` |
| Minimal logging | `warn` |
| Performance testing | `error` or `silent` |
### Common Log Patterns
**Startup messages**:
```
Server started on port 8000
Meilisearch started on port 7700
Loading channels...
```
**Media source sync**:
```
Syncing Plex library: Movies
Found 500 items in library
Sync completed in 5.2s
```
**Streaming issues**:
```
FFmpeg process started for channel 1
Stream error: Connection reset by peer
FFmpeg process exited with code 1
```
**Search indexing**:
```
Indexing 1000 programs...
Index update completed
```
### Increasing Verbosity Temporarily
To temporarily increase log verbosity for debugging:
1. Set `LOG_LEVEL=debug` environment variable
2. Restart Tunarr
3. Reproduce the issue
4. Check logs for detailed information
5. Reset log level when done
For Docker:
```bash
docker run -e LOG_LEVEL=debug ... chrisbenincasa/tunarr
```
## Performance Considerations
- **Higher log levels** (`debug`, `trace`) generate more output and may impact performance
- **Log rolling** helps manage disk space but adds slight overhead during rotation
- **Streaming logs** via API maintains an open connection; close when not needed
- Consider using `info` level for production and `debug` only when troubleshooting
## Log Output Destinations
Tunarr outputs logs to multiple destinations:
| Destination | Format | Description |
|-------------|--------|-------------|
| Console (stdout) | Pretty-printed | Colored, human-readable output |
| Log file | NDJSON | Machine-parseable JSON format |
Console output includes:
- Colored log levels
- Timestamps
- Source file information (in development mode)
- Formatted messages
Example console output:
```
[INFO] 2025-01-18T04:00:00.000Z [ChannelService] Channel 1 started streaming
[DEBUG] 2025-01-18T04:00:01.000Z [FFmpegService] FFmpeg args: -i input.ts -c copy output.ts
[ERROR] 2025-01-18T04:00:02.000Z [StreamService] Stream failed: connection timeout
```

50
docs/getting-started/run.md
View File

@@ -54,17 +54,45 @@ If using Docker Desktop, before running the Tunarr container, you have to use th
Tunarr has various command line / environment variables for configuration. These are listed below.
| Environment Variable | Command Line Flag | Default value | Description |
| ---------------------- | ----------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TUNARR_DATABASE_PATH` | `--database` | `''` | Sets the path where Tunarr will write its data to. **NOTE** Do not set this if using docker; use a bind mount pointed to `/config/tunarr` instead. |
| `TUNARR_SERVER_PORT` | `--port`/`p` | 8000 | Sets the port that the Tunarr server will listen on. **NOTE** When using Docker prefer using a port mapping than setting this. |
| `TUNARR_SERVER_ADMIN_MODE` | `--admin` | FALSE | Starts Tunarr in [admin mode](/configure/system/security/#admin-mode) |
| `TUNARR_SERVER_PRINT_ROUTES` | `--print_routes` | FALSE | Prints all of Tunarrs server routes at startup |
| `TUNARR_SERVER_TRUST_PROXY` | `--trust_proxy` | FALSE | Enables [trust proxy](/configure/system/security/#trust-proxy) for using Tunarr behind a reverse proxy |
| `TUNARR_BIND_ADDR` | N/A | `0.0.0.0` | Sets the interface that Tunarr will attempt to bind its server to. **NOTE** Change at your own risk! By default, Tunarr listens on all network interfaces |
| `TUNARR_USE_WORKER_POOL` | N/A | FALSE | Set to true to enable experimental support for Tunarr's worker threads |
| `TUNARR_WORKER_POOL_SIZE` | N/A | `cpus().length` | Control the number of worker threads Tunarr creates in its pool. It's recommended to use no more than the number of CPUs on the host system |
| `TUNARR_DEBUG_REDUCE_SEARCH_INDEXING_MEMORY` | N/A | TRUE | By default, Meilisearch will attempt to [reduce search indexing memory usage](https://www.meilisearch.com/docs/learn/self_hosted/configure_meilisearch_at_launch#reduce-indexing-memory-usage), which can have an [impact on file storage](https://github.com/chrisbenincasa/tunarr/issues/1558). Setting this to `false` will skip that. Not available for Windows users. |
### Server
| Environment Variable | Command Line Flag | Default | Description |
| -------------------- | ----------------- | ------- | ----------- |
| `TUNARR_DATABASE_NAME` | `--database` | `''` | Sets the path where Tunarr will write its data to. **NOTE** Do not set this if using Docker; use a bind mount pointed to `/config/tunarr` instead. |
| `TUNARR_SERVER_PORT` | `--port`/`-p` | `8000` | Sets the port that the Tunarr server will listen on. **NOTE** When using Docker, prefer using a port mapping instead of setting this. |
| `TUNARR_BIND_ADDR` | N/A | `0.0.0.0` | Sets the interface that Tunarr will bind to. By default, Tunarr listens on all network interfaces. **NOTE** This generally does not have to be changed. |
| `TUNARR_SERVER_TRUST_PROXY` | `--trust_proxy` | `false` | Enables [trust proxy](/configure/system/security/#trust-proxy) for using Tunarr behind a reverse proxy. |
### Logging
| Environment Variable | Command Line Flag | Default | Description |
| -------------------- | ----------------- | ------- | ----------- |
| `LOG_LEVEL` | N/A | `info` | Sets the log level. Valid values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `silent`. Overrides the UI setting. |
| `LOG_DIRECTORY` | N/A | (data dir) | Sets a custom directory for log files. |
### Search (Meilisearch)
| Environment Variable | Command Line Flag | Default | Description |
| -------------------- | ----------------- | ------- | ----------- |
| `TUNARR_MEILISEARCH_PATH` | N/A | (auto-detected) | Path to the Meilisearch binary. Tunarr will search common locations if not set. |
| `TUNARR_SEARCH_PORT` | N/A | (random available) | Port for the embedded Meilisearch instance. |
| `TUNARR_SEARCH_MAX_MEMORY` | N/A | (unlimited) | Maximum memory for Meilisearch indexing (e.g., `1024Mb`, `2Gb`). See [Meilisearch docs](https://www.meilisearch.com/docs/learn/self_hosted/configure_meilisearch_at_launch#max-indexing-memory). |
| `TUNARR_SEARCH_MAX_INDEXING_THREADS` | N/A | (all cores) | Maximum threads for Meilisearch indexing. Useful for limiting CPU usage. |
| `TUNARR_SEARCH_REDUCE_INDEXER_MEMORY_USAGE` | N/A | `true` | Reduces Meilisearch memory usage during indexing. See [Meilisearch docs](https://www.meilisearch.com/docs/learn/self_hosted/configure_meilisearch_at_launch#reduce-indexing-memory-usage). May [impact file storage](https://github.com/chrisbenincasa/tunarr/issues/1558). Not available on Windows. |
| `TUNARR_DISABLE_SEARCH_SNAPSHOT_IN_BACKUP` | N/A | `false` | When set to `true`, excludes Meilisearch snapshots from backups. The search index will be rebuilt on restore. |
### Performance
| Environment Variable | Command Line Flag | Default | Description |
| -------------------- | ----------------- | ------- | ----------- |
| `TUNARR_USE_WORKER_POOL` | N/A | `false` | Enables experimental worker thread pool for background tasks. **NOTE** This is experimental. |
| `TUNARR_WORKER_POOL_SIZE` | N/A | (CPU count) | Number of worker threads in the pool. Recommended: no more than the number of CPUs on the host. |
### Debug
| Environment Variable | Command Line Flag | Default | Description |
| -------------------- | ----------------- | ------- | ----------- |
| `TUNARR_SERVER_PRINT_ROUTES` | `--print_routes` | `false` | Prints all server routes at startup. Useful for debugging. |
## Hardware Transcoding

34
docs/index.md
View File

@@ -4,7 +4,35 @@ Create live TV channels from media on your Plex/Jellyfin servers, and more!
Configure your channels, programs, commercials, and settings using the Tunarr web UI.
Watch your channels by adding the spoofed Tunarr HDHomerun tuner to Plex, Jellyfin, or Emby. Or utilize generated M3U files with any 3rd party IPTV player app.
Watch your channels by adding the spoofed Tunarr HDHomeRun tuner to Plex, Jellyfin, or Emby. Or utilize generated M3U files with any 3rd party IPTV player app.
<div class="grid cards" markdown>
- **[Installation](getting-started/installation.md)**
---
Get Tunarr up and running with Docker or standalone binaries.
- **[Setup](getting-started/setup.md)**
---
Initial configuration and connecting your first media source.
- **[Channels](configure/channels/index.md)**
---
Create and configure your virtual TV channels.
- **[Scheduling](configure/scheduling/index.md)**
---
Organize your channel programming with powerful scheduling tools.
</div>
## What is this?
@@ -13,6 +41,6 @@ Tunarr was originally a fork of [**dizqueTV**](https://github.com/vexorian/dizqu
Tunarr has the following goals:
- Modernize the stack, both backend and frontend
- Stabilize the program, fix bugs, and improve performance (Tunarr currently is developed and tested on Node 22.13.1, which offers [non-trivial performance improvements](https://blog.rafaelgss.dev/state-of-nodejs-performance-2023) over previous versions)
- Stabilize the program, fix bugs, and improve performance
- Modernize and "prettify" the Web UI
- And of course, **Add a ton great new features!**
- And of course, **add a ton of great new features!**

6
mkdocs.yml
View File

@@ -92,6 +92,10 @@ nav:
- configure/clients/index.md
- Plex: configure/clients/plex.md
- Jellyfin: configure/clients/jellyfin.md
- System:
- configure/system/index.md
- Backup: configure/system/backup.md
- Logging: configure/system/logging.md
- Misc.:
- FAQ: misc/faq.md
- Common Issues: misc/common-issues.md
@@ -128,7 +132,7 @@ extra:
link: https://discord.gg/nYkb7MhPfD
plugins:
# - glightbox
- glightbox
- search
watch: