Positron User's Guide: Common Tasks

This section of the guide will help you get started using positron by example. It does not try to explain every command in positron, but will guide you through common scenarios and show you how to use positron in those cases. See the Command Reference for an exhaustive list of positron commands and options.

For all of these tasks, you must connect your Neuros to your computer and mount it. When you are finished and ready to disconnect the Neuros, you must unmount it. This is very important because Linux buffers disk writes, and if you do not unmount before disconnecting, it is possible to corrupt the Neuros database. (See Troubleshooting for what to do if that happens.)

Adding Files

In this section, we will manually add files to the Neuros. If you want to add all your music and have positron automatically keep it up to date, see the next section on "Synchronizing the Neuros."

To add a music track to the Neuros, just type:

positron add my_music_track.mp3

This will copy my_music_track.mp3 to the default music directory on the Neuros (usually "MUSIC").

You can also add a whole directory of music files to the Neuros:

positron add my_directory_of_music

Positron will preserve the directory structure. Don't worry if the directory contains some files the Neuros can't play. Positron checks the contents of each file and will only copy it over recognized music files (only MP3 and Ogg Vorbis at this point). Additionally, positron will never overwrite a file on the Neuros if it already exists. You can use this as a sort of "poor man's sync" by just adding the same directory whenever its contents change. Only new music files will be copied.

If you want to add some files and a directory and specify its destination on the Neuros, you can do that with:

positron add sourcefile1.mp3 sourcefile2.mp3 anotherdir /mnt/neuros/tunes

This will place a copy of sourcefile1.mp3, sourcefile2.mp3, and anotherdir in /mnt/neuros/tunes.

Synchronizing the Neuros

To synchronize your Neuros with your computer, first you need to configure your Neuros and setup a syncpoint. (Although you can always run this command without a syncpoint, it won't do much without one.) Once that is all set, all you have to do is run:

positron sync

and that's it! Positron will do several things now:

Scan your syncpoints for new music files and copy them to the Neuros.
Scan your Neuros for new recordings and copies them to your computer. (This step is skipped if you didn't specify a directory to copy them to during configuration.
Remove unused space from your database if needed. This is called "packing."

If you decide you don't want a particular Neuros recording on your computer, you can delete it using rm or some other standard file utility. Positron remembers which recordings have been copied, and won't copy them again. Of course, you can always manually copy a recording from the Neuros using cp or some other file utility. The Neuros stores recordings in the WOID_RECORD subdirectory.

If you want positron to forget what recordings it has copied to your computer, use the command:

positron sync --reset-recordings

Similarly, you can get positron to forget what music files you have deleted (see next section) using

positron sync --reset-deleted

Removing Files

Sometimes you want to remove a music file from the Neuros. You should never, ever do this using normal file utilities. They will remove the file on disk, but not remove the database entry. Your Neuros will still show the track in its song list, but when you try to play it, the behavior will be unpredictable.

To remove a music track you can type something like:

positron del /mnt/neuros/music/test.mp3

Positron will both delete the file on the Neuros and remove the entry from the database. You can delete many files with one command, and you can even delete whole directories of files! Positron will never delete files (regardless of type) that are not referenced in the Neuros database, nor will it delete directories unless they are empty.

Positron will remember which files you have deleted and not recopy them when you next synchronize. This way you can remove files on your Neuros that you don't want to listen to without having to remove them from your syncpoint. However, you can always manually add a track using positron add whether or not it is in the list of deleted tracks. As mentioned above, you can clear the delete list using:

positron sync --reset-deleted