Control Pin Settings Issues Troubleshooting FAQ


Latest version: 1.0.11 (Dec 27th 2013)
Changelog

IMPORTANT: for proper operation on Android 4.2+, the filesystem must be mounted AFTER the music player app's process that will be accessing it has been started. See Remount for details
NOTE: the new Auto-remount setting should take care of this automatically, if enabled (the default)

GMusicFS exposes your cloud Google Music collection as a filesystem.

The goal is to bring Google Music streaming support to most third party music players like Poweramp, PlayerPro and many others. From the point of view of these apps, Google Music tracks will look like regular files.

GMusicFS only stores track metadata and album art on the SD card. Audio data is only accessed during playback, either streamed from the network or cached from local storage.

To properly uninstall GMusicFS, see uninstalling.

This document will be completed over time, so check back often!

Requirements

Third party music players setup

GMusicFS should work with most music players. Some of them require additional initial setup to work well with GMusicFS.

Poweramp

If after a Sync, tracks are not playing and have weird titles, you must trigger a database rescan. Try Menu > rescan in either the Folders or Library tab. If it doesn't work, trigger a full rescan with Settings > Folders and Library > Full rescan.

For synced playlists to be listed under Library > Playlists, you must import them using Settings > Folder and Library > Playlist Import/Export > Import System Library Playlists.

To avoid having duplicate tracks, you must exclude a folder in Poweramp's configuration, the first time the GMusicFS filesystem is mounted:

PlayerPro

If PlayerPro doesn't show album art for some or all Google Music tracks, force it to rebuild album art by deleting it with Settings > Browsers > Delete album artwork.

n7player

n7player has its own library management and some options must be disabled to avoid its automatic rescan to remove tracks managed by GMusicFS.

Control

The Control tab allows you to select your Google Music account, perform Sync and control mounting of the filesystem. The close button (X) in the action bar unmounts the filesystem and cleanly exit GMusicFS.

Account

Click to select the Google Music account holding your music. The first time, you will be prompted to authorize GMusicFS to access the Google Music service for this account. After the account is selected, a Sync will be automatically performed if none was previously done, and the filesystem mounted.

Note that initial syncing can take some time because of the downloading of album art. Subsequents syncs are much faster as album art is not redownloaded.

Sync

Syncing is the operation of fetching/updating your Google Music collection metadata and album art, associated to your account. No music is ever downloaded. When your music collection has changed (you uploaded or deleted tracks), you can Sync at any time to reflect the change in GMusicFS.

For quick testing, you can limit the number of tracks fetched.

Remount

This operation mounts the filesystem if it is unmounted, or if it is already mounted, will unmount it and mount it again. When the filesystem is mounted, a notification will appear with a "Remount" button to allow quick remounting from anywhere. The filesystem needs to be mounted to be accessible from music players apps.

IMPORTANT on Android 4.2+ (if auto-remount is disabled)

On Android 4.2+, there are further conditions for music player apps to be able to access the filesystem: A music player app can access the filesystem (see the mount) only if the filesystem is mounted after the player app's process was started. Consider the following scenario:

This scenario works because mounting happened after the music player app was started. Now, consider this scenario: In this second scenario, music is not playing because GMusicFS mounted the filesystem before the player app was launched. To fix this you must remount the filesystem:

Unmount

This operation unmounts the filesystem. When unmounted, music apps will not be able to stream Google Music files.

Rescan

This operation trigger the Android Media Scanner on mp3 files managed by the filesystem. The Android Media Scanner is responsible of adding audio files to the Android music database which is used by most music players not having their own library management. Although it should not be needed in most cases (a rescan is automatically performed after syncing), it may be useful if Google Music tracks do not appear in a music player app.

Cleanup

The filesystem must be unmounted for this operation to be available.

This operation remove all filesystem files from the SD Card (metadata and album art) and resets GMusicFS to its initial state, when it is launched for the first time. It will also remove all Google Music entries from the Android music database (after cleanup, this can takes several seconds to be effective). Use this to cleanup everything and start from scratch.

Pin

The Pin tab presents the list of albums that you can individually pin for caching to SD Card. Currently, it is not possible to pin individual tracks. By pinning your most listened albums you can reduce network data usage which can be useful on metered mobile connections, and it is not prone to shaky network conditions.

The check mark right to each album shows its pinned state. If it is pinned, the number of tracks that are cached are shown below the check mark.

Albums can be filtered by All / Pinned / Unpinned status.

To pin or unpin an album, simply tap it. It is also possible to pin an album from the notification area, when a track is playing whose album is unpinned. Unpinning will delete all cached tracks for that album from the local storage.

Only tracks whose album are marked pinned are considered for caching.

When an album is marked pinned, a track of that album will be actually cached to local storage the first time you play (stream) it. If a track is cached when you play it, the cached file will be used instead of streaming from Google servers. For a track to be cached the first time it is played, it must be played in full from the point of view of the filesystem (which depending on the "Buffer length" setting can happen some time before you actually reach the end of the song in your music player!). Seeking in a track for which caching is not yet complete discards the caching in process.

When playing a track, you can check whether GMusicFS use a cached file or is streaming. And in the later case, you can check if it is caching (writing) the track to storage. This information is displayed both in the Control tab and the notification area.

You can set the location of cached tracks in Settings > Cache directory. It is possible to specify an absolute directory to point to additional storage with high capacity (eg, something else than the internal SD Card). By default, cached tracks are stored at the root of the SD Card, in a hidden ".gmusicfs.cache" directory.

Settings

Stream buffering

These settings control buffering of audio data during track playback and are only relevant when streaming from Google servers.

Buffer length

This is the duration in seconds of audio data that is prefetched while playing. This duration of audio will be at max available in advance, but it can be less in not ideal or slow network conditions. This setting can help to prevent drop out of audio on unreliable networks.

When playing a track, the buffer fill status in percent is displayed in both the Control tab and the notification area. A buffer fill status of 100% indicates that the buffer has the configured buffered length of audio available. Note that it is normal for the buffer fill to remain near 0% for some time at the beginning of the playback of a track, as the music player and/or the kernel may do its own buffering, reading data as fast as it can.

Pre-buffering length

This is the duration in seconds of the audio data that must be downloaded before playback begins. It doesn't mean that audio playback is delayed by this duration: it is only delayed by the time it takes to download this duration of audio which will usually be much shorter. For example, if this setting is set to 2s and it takes 0.3s to download it, playback is delayed by 0.3s.

It is not recommended to change this setting from the default value (0: disabled), unless you get audio drop outs at the beginning of tracks.

Track caching

Cache directory

This is the directory where tracks from pinned albums are stored. See Pin.

Clear cache

Displays the cache size and allows to clear it.

Auto-remount

These settings are only present when GMusicFS runs on Android 4.2+. If enabled (the default), GMusicFS will automatically remount the filesystem when it detects a music player is started for the first time, so you do not have to do it manually.

All music apps

If enabled, auto-remount applies to all apps able to handle audio (except file managers). If disabled, you must select which apps will trigger auto-remount (see below)

Selected music apps

Click to select apps that must trigger auto-remount.

Metadata

Append mode

Optionally append a custom string to albums and/or track titles, depending on mode. In a music player, this allows to differentiate Google Music tracks and albums managed by GMusicFS from regular files.

Append string

The string to be appended to albums and/or track titles.

Debug

Enable logging to file

For debug purpose. Do not enable for normal operation as it may slow things down.

General

Generate m3u playlists

If this setting is enabled, GMusicFS will generate a m3u playlist file for each Google Music playlist, when syncing playlists. This is only needed for playlists to be accessible in some music players (such as MortPlayer) that can read m3u playlists, but cannot access Android music database playlists.

Generated playlists can be found in folder <SD Card root>/gmusicfs/<account>/Playlists.

Enabling this setting automatically generates the m3u playlists. Disabling this setting delete them.

Notification visibility

This setting launches a page that gives you the option to hide the mount notification in the notification area. This notification is made mandatory by Android as GMusicFS runs a foreground service when the filesystem is mounted. However, Android gives you the ability to hide it. Simply untick "Show notification" in the launched page. Disabling the notification will also hide any toast message displayed by GMusicFS (used mostly to display error messages during playback).

Start on boot

If enabled, GMusicFS will start and mount the filesystem on boot. On Android < 4.2, the filesytem should be accessible straight away. On Android 4.2+, mount remarks apply.

Uninstalling GMusicFS

Before uninstalling GMusicFS, make sure to follow these steps to clean up the Android music database and filesystem files: If you uninstalled GMusicFS without following above steps:

Known issues and limitations

Troubleshooting

The remount operation fails

In rare cases, unmounting prior to mounting can fail. That may happen if an app has a file managed by the filesystem still opened. Kill this app (with a task killer or Android's "Force Stop"), and unmount again.

If remount fails and the filesystem was not previously mounted, please report this issue with the exact error message on the XDA forum thread.

The remount operation fails with code 126

If you get this error:

Mount script execution failed (code: 126)
sh: [1]: /data/data/com.bubblesoft.android.gmusicfs/files/wrapper.sh: can't execute: Permission denied.

To fix it, enter the following commands in the Terminal app:

$su
$chmod 700 /data/data/com.bubblesoft.android.gmusicfs/files/*

Then try mounting again.

A track doesn't play in a music player

For example, PlayerPro would display an error message: "Sorry, the player do not support this type of audio file".

On Android 4.2+, the most likely case is that the music player app was started before the filesystem was mounted. Just remount the filesystem. You may have to also reopen the failing track for it to play (play another track and select the previous track to force the music player to close the previous track).

PlayerPro doesn't show album art

If PlayerPro doesn't show album art for some or all Google Music tracks, force it to rebuild album art by deleting it with Settings > Browsers > Delete album artwork.

Poweramp doesn't show Google Music tracks (or metadata is incomplete)

First, make sure the filesystem is mounted. Try Menu > rescan in either the Folders or Library tab. If it doesn't work, trigger a full rescan with Settings > Folders and Library > Full rescan.

Google Music tracks have disappeared from my media player

If a media player do not show Google Music tracks and they disappear unexpectedly at some point, do a manual rescan in the Control tab. If the media player does not use the Android database to list music, trigger a rescan in the media player itself. This situation can sometimes happen if the filesystem is not unmounted cleanly, for example if GMusicFS crashes.

FAQ

Why is the first Sync slow ?

The first time you select your account and Sync, all the album art is downloaded and stored on the SD Card. Depending on the size of your collection, this can take quite a bit of time. Subsequent Sync will only fetch additional album art and is a lot faster.

How can I disable the many root permission toast messages ?

Launch SuperSU. In the Apps tab, click on GMusicFS and change the Notifications setting to "Disabled". Do the same for the "ADB shell" entry.

How can I disable the notification when mounted ?

GMusicFS needs to run a foreground service when the filesystem is mounted. Android makes it mandatory to have a notification whenever a foreground service is started. You can still hide the notification: This will also hide any toast message displayed by the app.

Where the filesystem is mounted ?

The filesystem is mounted as a subdirectory of the SD Card, under <sdcard root>/gmusicfs. When mounted, the backing filesystem metadata directory is found under <sdcard root>/gmusicfs.meta. When unmounted, the backing directory becomes <sdcard root>/gmusicfs.

Can I use GMusicFS for something else than music playing ?

GMusicFS is meant to be used for music playback only.

In particular, it is not meant for downloading tracks, although nothing prevents you from doing so. If you download tracks, it will be slow (capped by Google at around 40Kb/s) and downloaded tracks will contain a few seconds of silence at the beginning. Probably not what you want, so don't do it.

How can I remove Google Music tracks from the Android music database ?

The Cleanup operation in the Control tab will do that.

Does scanning track metadata for populating the Android music database make network requests to Google ?

No as this would be way too slow and ineficient. The only requests made to Google servers is during the Sync operation and when actually playing music.

Changelog

1.0.11 (Dec 27th 2013)

1.0.10 (Dec 23th 2013)

1.0.9 (Dec 13th 2013)

1.0.8 (Dec 11th 2013)

1.0.7 (Oct 15th 2013)

1.0.6 (Oct 10th 2013)

1.0.5 (Sept 7th 2013)

1.0.4 (July 7th 2013)

1.0.3 (Jun 2th 2013)

1.0.2 (May 30th 2013)

1.0.1 (May 27th 2013)