Using PDF and image files in Set Lists

A Set List is more than a list of songs. In addition to songs, you can add PDF and image files as entries – for example scanned sheet music, chord sheets, lyrics or lead sheets. During a performance you simply step through your Set List, and each PDF or image is shown full-screen, ready to play from.

Adding PDF and image files

You can add files to a Set List from the sources your device offers, such as:

• the local storage of your device,
• a memory / SD card,
• a cloud service (Google Drive, Dropbox, OneDrive, …).

Each file you add becomes a Set List entry. smartChord does not embed the file itself into the Set List – it keeps a reference to the file so the Set List stays small and the original file remains where it is.

Why references cannot simply be shared between devices

On modern Android, apps do not get free access to the whole file system. Instead, every file or folder is addressed through a device-specific location and an explicit permission that Android grants to the app. This has an important consequence:

A file reference that is valid on one device is not valid on another device. The internal paths differ from device to device, and the access permission granted on one device does not exist on the other.

In other words, Android’s file management deliberately does not allow you to exchange raw file paths between devices. If smartChord simply stored such a path, your Set List would work on the device where you created it, but the same entries would be unreadable after synchronizing or sharing the Set List to another device – because that path or permission does not exist there.

Our solution: the Local Folder

To make PDF and image entries portable, smartChord does not rely on device-specific paths. Instead, it stores every PDF and image entry by its plain file name (for example Summer of Sixty Nine.pdf) and resolves that name against a Local Folder whenever you open, share or export the entry.

Because only the file name is stored:

• the same Set List works on every device, as long as a file with the same name exists in that device’s Local Folder;
• you can move your files or point smartChord at a different Local Folder at any time, without having to re-link every entry.

By default the Local Folder is the app-specific directory /storage/emulated/0/Android/data/de.smartchord.droid/files/ with a setlist subfolder. You can change it in the Set List settings at any time.

Recommended setup

1. Define a Local Folder in the settings.
2. Store all your PDF and image files in this folder.
3. Make sure the folder content (the file names) is identical on all devices you use.

Changing the Local Folder

Because entries are stored by file name and resolved at the moment you access them, you can change the Local Folder whenever you like:

• Select a new Local Folder in the Set List settings.
• Make sure your PDF and image files exist in that folder using the same file names.
• Your entries are resolved against the new folder automatically – no manual re-linking required.

This lets you keep your files on an SD card, in a cloud-synced folder, or in any directory you prefer, and switch between them without breaking your Set Lists.

Automatic file recovery

When you open a Set List, smartChord tries to resolve each PDF and image entry by name in your Local Folder. If a file cannot be found there, smartChord automatically searches for a file with the exact same name in:

• the Android media database,
• the Local Folder, including its subfolders,
• the app-specific folder.

If a matching file is found, the entry is used (and a broken reference is repaired). If no file is found, the entry is marked with an error icon so you can replace or re-assign the file manually.

Note: Moving or renaming a file on your device can still make it inaccessible, because smartChord does not know the new location and may not have permission to read it. Keeping all files in your Local Folder with stable names avoids this.

Synchronization and sharing

Synchronization. During synchronization, none of your PDF or image files are transferred to another device. Synchronization keeps only the Set List itself (its entries and references) in sync. On a second device the files must be present in the Local Folder using the same names.

Sharing a Set List. When you share a Set List via link, smartChord can include the actual PDF and image files in the shared package. On the receiving device, enable „Import songs along with PDF and image files“ during import to copy those files into your Local Folder. While the files are copied, a progress dialog shows each file name so you can follow the import. Afterwards the Set List opens and the entries resolve against the copied files.

If you prefer not to transfer the files this way, keep „Import songs along with PDF and image files“ disabled – only the Set List definition is imported, and the files must already exist in your Local Folder.

Keeping files up to date across devices

Copying every new PDF to every device by hand gets tiresome. The comfortable setup is to let your cloud service fill the Local Folder for you.

The idea: keep one folder in your cloud (Dropbox, Google Drive, OneDrive, Nextcloud) that holds all your PDF and image files. Mirror that cloud folder into a real folder on each device and point the Local Folder at it. From then on, a file you drop into the cloud folder on your computer appears on all your devices, and your Set List entries resolve it automatically.

Why you need a sync app

The official Dropbox and Google Drive apps are not enough. On Android they show your files inside their own app and keep them in their own private storage, where smartChord cannot reach them. What you need is a folder-sync app that mirrors a cloud folder into a real folder on your device:

• Autosync (Dropsync) for Dropbox, and its siblings for Google Drive, OneDrive and MEGA
• FolderSync, which supports many services including Dropbox, Google Drive, OneDrive, WebDAV and Nextcloud
• OneSync for OneDrive

Setting it up

1. Create a folder in your cloud account, for example smartChord/SetList, and put all your PDF and image files into it.
2. Install a folder-sync app on your device and connect it to your cloud account.
3. Create a sync pair: the cloud folder on one side, a folder on your device on the other, for example Documents/smartChord/SetList. Two-way sync is a good default. If you only ever add files on your computer, one-way (cloud to device) is the safer choice.
4. Let the first sync finish, so the files are really on the device.
5. In smartChord, open Settings, Set List, Local Folder and select exactly that folder. If your files are still in the previous Local Folder, smartChord offers to copy them into the new one.
6. Repeat steps 2 to 5 on every device.

The folder path may be different on each device. The file names may not: they are what a Set List entry is resolved by.

Good to know

• Ready for the stage. The files are real files on your device, so your Set List works without an internet connection. Most sync apps can be set to sync on Wi-Fi only, which keeps your mobile data free.
• Subfolders are fine. If you sort your files into subfolders of the Local Folder, smartChord still finds them: the automatic file recovery searches the whole folder tree.
• Renaming. A file renamed in the cloud is renamed on every device, and an existing Set List entry no longer finds it. Give a file its final name before you add it to a Set List. If you rename it later, use “Replace” on the entry to link it again.
• Deleting. With two-way sync, deleting a file on one device deletes it everywhere. If that makes you nervous, use one-way sync from the cloud to your devices.