AVSub Tips

Subsonic Playlists

Go to the playlists menu and right-swipe on a playlist. Tap the lightning bolt and it will set this playlist as the active playlist. You can now add to this playlist from anywhere in the app - find the track you want to add by browsing your media index, right swipe on the track and you'll see another lightning icon - tap this and the track is added to the active playlist.

Stop Downloads

If you want to stop a download, go to the cache view and long-press on the header. You'll get a popup.

AVSub Playlist

You can get to the now-playing playlist from anywhere in the app by swiping-down on the header.

Similar Artists

If you left-swipe on an artist or track when browsing your media, you'll get a radio icon. This will create a playlist of similar songs.

Create a Subsonic playlist from the current AVSub playlist

Go to the playlist menu and select Create Playlist - you can create an empty one, or one populated with the current playlist.

Background Cache Downloads

AVSub fully supports background downloads, so you can queue up a lot of downloads and put the app in the background.

Activity Spinner

You can cancel the activity spinner by tapping it. If you're playing a track and it starts buffering, tapping the spinner will stop the current playback.

Album Info

When you browse into an album, the top summary is called the Album Info. If you right swipe on this row, you can download the entire album, queue up the entire album or add the entire album to the active playlist. It's also got a left-swipe for Similar Artists.

Straight back to main menu

If you long press on the back arrow in the top left, it'll take you straight back to the main menu.


If you long-press (4-seconds) on the Chromecast button on the front screen it will reset the internal Chromecast system.

Digital output of (lossless) audio

If you've got the Apple Camera Connection Kit (CCK) you can stream audio direct to an external DAC. This means you can use AVSub as a digital transport. Audio resolutions of up-to 24bit/192khz are supported an AVSub even supports the studio mastering format DSD.

UI Colour

Don't like the AVSub colours? You can change the colour of the UI in the settings menu. You can also toggle the blurred backgrounds.

Second Server

You can define a second server in the settings. You can even have AVSub fail-over between the servers if one is not available.

Replay Gain

AVSub supports Replay Gain to normalise volume levels.

Hide Buttons for In-App Purchases

AVSub supports video/jukebox and Chromecast through in-app purchase. There's a button for each on the main menu. However if you don't want these, you can hide the buttons via the settings menu.

Shuffle Subfolders

If you press the "Play/Shuffle Subfolders" button it will play all tracks in the subfolders in sequential order. If you press and hold then it will shuffle them.

Chromecast Video Skip Button Time

You can change the amount of time that video will skip forward and back when casting videos in the settings.

OGG Patch!

Sometimes the length of transcoded OGG tracks is reported incorrectly. This can cause AVSub to think there's more of the track to come when it's actually finished - buffering hell! You can activate a patch to get around this from the settings - "OGG transcode patch".

Similar artists

If you swipe to the left on a table cell for an artist of album, you'll see a radio icon. Press this for a playlist of tracks from similar artists.

Re-scan media folders

You can ask Subsonic to rescan the media folders direct from the app - just go to Settings and it's the first button in the general settings section. The configured user must be an Administrator in Subsonic.


You can go straight to the track listing of any suggestion by tapping the album art.

Top Songs for an Artist

By default the top 10 songs for an artist are shown, but you can change this in the settings.

Favourite radio station

If you've got an iPhone 6S(+) or 7(+) you can use this feature. Go into Internet Radio Stations and left-to-right swipe in a cell to mark a radio station as favourite. Then, from the AVSub quick shortcut menu (press and hold the AVSub icon) you can instantly start playing your favourite station.

Manually load main folder

AVSub will automatically refresh the top-level information in your selected folder when it loads (or if you hit the refresh icon in the home screen). If you have a large music collection, AVSub can sometimes time-out loading that information. There's an option in the settings called "load folders manually" which will stop AVSub from doing this and only refresh if you hit the Refresh button on the Media Index screen.

Recently Played Today Widget

AVSub has a recently-played 'today widget' that appears on your home screen (swipe right on the lock screen), or from the AVSub quick shortcut menu.

Change Movie Details

If AVSub doesn't get the details for a movie right, long press on the poster in the main list and you can refresh the data.

Amazon FireTV Support

The Amazon FireTV has the ability to stream media directly to it, just like any Google Cast device. However this feature is pretty new to the FireTV (it's called the Fling API) and as such it's not as mature as the Google Cast device (even if it is a little more straight-forward under the hood!). As such, there are some limitation - these are detailed below.


The FireTV does not support playlists - you can only cast one media item at a time! However, AVSub will manage the playlist for you. The caveat to this is that AVSub must listen for the current track ending on the FireTV and queue uo the next one - meaning that AVSub must remain the active app on your phone or iPad. Full playlist management in AVSub is still available.

Audio Formats

The FireTV supports all the popular audio formats but in testing I've found the device to be a little picky. Sometimes it plays a track but doesnt send any updates back to AVSub. AVSub will recognise this scenario and try to keep in sync with the device. You will find that for audio in this situation, you cannot seek within it.


The FireTV works with video very similarly to Google Cast. You can setup a video transcoder for the FireTV just as you would for Google Cast - that is detailed in the guides section.

Enhanced Movie & TV Show Information

AVSub supports lookup of movie & TV meta information from TMDb. To identify files as movies or TV shows, AVSub must be told the media type for each Subsonic folder. By default it will use Audio, but you can change this in the Folder screen, which is on the Media Index screen. To set a folder to Movies, tap the movie reel icon. To set a folder to TV, tap the TV icon.

Folder structure

AVSub expects that for Subsonic folders identified as having movies or TV in, each movie or TV show will be inside a directory with the name of the movie or show. See the diagram for an explanation.

Movie Structure

TV Structure

Note that AVSub also supports season folders for TV shows.
If you would support for a different directory structure, please let me know.

Movie Directory & File Naming

AVSub will use the name of the movie directory to query for information. It parses the name of the folder to extract information that it can use in the query. AVSub is capable of parsing standard video filenames e.g Title.Of.The.Movie.YEAR.Source.Codec.

The best/simplest format for directories is [name of movie] (year)

Example Movie Structure

TV Directory & File Naming

AVSub will use the name of the TV directory to query for information. It parses the name of the folder to extract information that it can use in the query. AVSub is capable of parsing standard video filenames e.g Title.Of.The.Show.YEAR.Source.Codec.

The best/simplest format for directories is [TV show] (year).
AVSub also supports season folders for TV shows.

Example TV Structure

Changing Movie or TV Show Information

AVSub will use the first movie or TV show that is returned from TMDb. In some cases this is not correct, and in some cases TMDb doesn't find a match (this will result in the default movie or TV poster being used). You can refresh this information by long-pressing the poster. You can then edit the name sent to TMDb and select from the results returned


Frequently Asked Questions

Q. How can I return to the main menu quickly?

A. If you long-press on the back arrow, you will return to the main menu.

Q. Does AVSub browse by folder structure or ID3 tag?

A. AVSub can browse by both folder structure and ID3 tag. Toggle from the configuration.

Q. Why can't I see my playlists?

A. Is it visible to the Subsonic user you're using? Edit it and make it visible to all, or create it under the use you've defined in AVSub.

Q. What is the setting 'Use ignoredArticles'?

A. ignoredArticles is a list of words that you define in the Subsonic settings. If AVSub uses this setting, then it will ignore the words in the list (such as 'the') from the names of the folders returned in the music index. For example, this means that 'The Beatles' will appear in 'B' instead of in 'T'.

Q. What does AVSub cache?

A. AVSub can cache videos, songs, albums, playlists and album art. Caching of album art makes browsing with album art displayed much quicker.

Q. How can I stop a direct download?

A. To stop a direct download, go to the Cache section and long-press on the header . A popup will appear and you may chose to cancel the download.

Q. I've deleted everything from my cache - it's not 0%?

A. Deleting from the cache does not remove associated album art, as it could be used in more than one place. To completely empty your cache, use the big red CLEAR CACHE button in the Configuration section.

Q. Will AVSub work with forks of Subsonic such as Madsonic and Ampache?

A. Yes. AVSub is also compatible with Supersonic, Iposonic, Madsonic, Futuresonic, Supysonic and Ampache. In fact, any variant of SubSonic that support the Subsonic REST API standard should work.

Q. Why does AVSub need a licensed Subsonic server?

A. AVSub uses the REST API of Subsonic, which after the initial 30 day trial, becomes a premium feature. But Subsonic Premium is only £7/$12 a year - it's well worth it!

Q. Does AVSub support HTTPS?

A. Yes, both regular and self-signed certificates are supported, including the default Subsonic certificate.

Q. Does AVSub play video?

A. Yes! As of version 8, AVSub can be upgraded to play video. It can either stream direct from Subsonic, or cache it and play it later. Note that due to a bug in Apple AVPlayer, video in iOS8 with a self-signed certificate is not reliable. Non SSL and valid certificates all work fine.

Q. How do I report a bug/request a feature?

A. See the about page for submitting bugs and feature requests.

Q. Whats with the name change from CarSub?

A. Initially the app was written for use in the car, but with the addition of more features and especially video, I felt it was time to give it a name more representative of it's features.

Q. How do I enable video?

A. Video can be enabled from the About section. Simply click the video upgrade button and follow the on-screen prompts. There is no need to restart - video will be enabled straight away. Don't forget to check your Subsonic transcoding settings.

Q. What video formats does AVSub support?

A. AVSub supports FLV & MKV containers, X264 video & MP3/Vorbis audio. These are the formats in Subsonics two default transcoding settings. It is recommended that you stick to the FLV container, since due to an FFMPeg restriction, the length of video is not provided in the MKV container.

The FLV transcoder can be setup (in Subsonic > Settings > Transcoding) as follows:
Name: video-flv
Convert from: avi flv mpg mpeg mp4 m4v mkv mov wmv ogv divx m2ts
Convert to: flv
Step 1: ffmpeg -i %s -async 1 -b %bk -s %wx%h -ar 44100 -ac 2 -v 0 -f flv -c:v libx264 -preset superfast -threads 0 -

Untick Enable this transcoding for all existing and new players then click Save.

Go to Subsonic > Settings > Players and assign the video-flv transcoder to the user defined in the AVSub settings.

Q. How do I cache videos?

A. AVSub will cache a video if you left-to-right swipe on it in the lists and press the download icon, just like other songs or albums. It does not cache videos while playing.

Q. I see all my videos in one list when I press the Videos button?

A. This is what Subsonic returns when you ask specifically for videos. However you get a much better view of videos if you browse to your video folders using the Media Index button.

Q. I keep accidentally wiping out my now-playing list by selecting a track directly!

A. If you do this, go to the Now-Playing list straight away and long-press on the header. You can then choose to go back to the previous playlist. Note that if you start to add other tracks, or interact with the tracks, the app assumes that you meant to do this and discards the previous list.

Q. I can't play video reliably over SSL with a self-signed certificate.

A. In iOS8 there is a bug in Apples AVPlayer library that causes inconsistent video playback. Until this is fixed, either disable SSL, install a proper certificate or cache the video locally on the device.

Q. Why does my track stop before the end?

A. I've seen instances where a track does not play to the end when the track is being transcoded to a different bitrate. For instance, having the Max Audio Bitrate set to 160 will transcode everything to 160kbps in Subsonic. Sometimes, especially with M4A tracks, the transcoding doesnt report the correct length so the track is cut short - this is a problem at the server end. To get around this, set Max Audio Limit to No Limit.

Q. What's Jukebox mode?

A. Subsonic's Jukebox Mode allows you to play music direct on the server hardware. So, if you have your Subsonic server connected to your hi-fi, in Jukebox mode, when you select a track, it will play on your hi-fi, not your device. Jukebox Mode in AVSub allows you to use AVSub like a remote control for your music library, and is fully integrated with the other features like the now-playing queue.

Q. What's the ideal setup for AVSub and lossless audio?

A. AVSub will play the original file when on WiFi (you can disable this in the settings). When on cell/mobile, AVSub will automatically request that audio is transcoded to MP3 - this improves playback performance on slow mobile networks and saves on data. If you want to allow lossless on mobile/cell, then disable the transcoding of these in the Subsonic settings.

Q. How can I tell the current stream format?

A. You can see the stream format of the current stream from the now-playing playlist screen (format is on the 3rd line).

Q. Whats that little green dot on the progress line?

A. This is the download indicator. AVSub downloads the track as it's being played. It also downloads the next one once the current is finished to ensure smooth gapless playback.

Q. Why can't I seek beyond the downloaded indicator (green dot)?

A. Formats such as FLAC/ALAC cannot be jumped into, and require all of the data to be present up to the point you want to play. You cannot seek to a position until the data is available. This is one of the reasons that AVSub downloads the entire track as quickly as it can.

Formats such as MP3 are what's known as header-less formats - that is, you can jump into the middle of the data and start playing it. AVSub will offer this in MP3 in the near future - I just need to code it!

Q. Should I enable 24bit/192kHz?

A. Unless you're connecting your iOS device to a DAC via the Apple Camera Connection Kit, this setting will not have any effect. See the question below too.

Q. How can I output 24bit/192kHz?

A. Up to 24bit/192kHz is supported via the Apple Camera Connection Kit - this is the only way an iOS device can output pure digital data. Connect this to your iPad, then connect the USB to your DAC - enable the 24 bit/192kHz setting in the settings - and AVSub will output at the original resolution.

Q. I get gaps between tracks when using Chromecast.

A. Chromecast works by having a sender app and a reciever app. AVSub is the sender app, and uses the default Chromecast receiver app. Unfortunately the default Chromecast reciever app does not yet support gapless playback. As soon as it does, AVSub will support it.

Q. Chromecast stops if I cast direct from the AVSub cache and the app is in the background.

A. AVSub will finish serving the current song when the app goes into the background, but then it suspends. Apple rules state that apps must suspend in the background unless they do a specific list of things - playing audio is one of them, which is why AVSub works in the background when it is directly playing audio. When AVSub is serving a Chromecast from it's own cache, it's not directly playing audio. The way to successfully cast direct from AVSub cache is to keep it in the foreground. Just keep it on the now-playing screen and it will be fine.

Q. My Chromecast is unresponsive - What do I do?

A. The Chromecast is a great system but can sometimes get very confused! In this instance, it's best to restart the Chromecast and initialise AVSub's internal Chromecast system. You can do this by pressing and holding the Chromecast button on the front screen for 5 seconds. A message will appear to indicate that AVSub's internal Chromecast system has been reset.

Q. Are bookmarks saved in the cache also?

A. YES - if the file is in the cache. However they don't show in the Bookmarks screen because this is for server bookmarks. You can start from your cached bookmarked position by finding the bookmarked file in the cache and playing it - if it's got a bookmark against it, it will play from that position. You will also be able to see the position of the bookmark in the cache list for the file. To play a bookmarked cached file from the begining, start it and press the "previous track" button.

Q. Why can't I see the bookmark icon for my audiobook?

A. The bookmark button is on the panel at the bottom of the Now Playing screen. Swipe it from left to right to find it.

Q. Why does AVSub display two colour default album art sometimes even when I have actual cover art?

A. In some circumstances, Subsonic will create album art on-the-fly. This is the album art you are seeing (two colours with the artist/album name on), and is being returned by Subsonic, not AVSub.

If you have the correct album art and the default art is still being displayed, you need to re-tag the album art for the track/album in question. I have observed Subsonic send the default art back when very large cover art files are used - it seems to have a problem resizing these files - especially for the thumbnail images that AVSub uses.

Q. Why does replay-gain not always apply to my MP3 streams?

A. Replay-gain relies on values in the meta-data of the stream. In an MP3 stream, this data is at the end. If AVSub is streaming the MP3 it won't get to the end until it's received all the data, which is too late. As long as you've got a reasonable connection you should be ok with everything except the very first track. As long as AVSub can pre-cache the next track before it starts playing it then the replay-gain information will be applied correctly.

FLAC files and cached MP3 files are not affected by this.

Q. How do I setup transcoding in Subsonic for Google Cast/Amazon FireTV Video support?

A. You can find the guide for setting up transcoding in the guides section.

Q: Why doesn't AVSub start properly from CarPlay?

CarPlay won't start AVSub when the iPhone is locked. I don't know why! So, make sure that AVSub is running before you connect your iPhone to your head unit, or unlock your iPhone before starting AVSub from the CarPlay interface.

Q: Can I adjust the playback rate?

When playing spoken audio (books, podcasts) you are able to adjust the playback rate. Even though AVSub configures CarPlay to configures to allow rates from 1.0 to 1.9, it won't go over 1.3 from CarPlay. Again, I don't know why! If you want to go higher than 1.3, you can do it from the iPhone.

Q: What does "CarPlay hierarcy depth limited reached" mean?

CarPlay is limited to 5 levels of information. If you have a deeply nested music structure, AVSub can only get 4 levels into it (because the Media tab is the first level). AVSub cannot get around this restriction. Browsing in ID3 mode should remain in this limit, and for most artist/album structures, media is accessible within this limit.

Q: How can I seek within a track?

You can press and hold the fwd/back buttons to seek within a track.