QuickDoc.txt

This document is the replicate of the wiki (version of the 9th of july, 2017) accessible here: https://git.afola.ovh/Jeux/SonicScoutDriver/wikis/home


WHAT IS SONIC SCOUT DRIVER?

The Sonic Scout Driver is a tool to explore the Sonic Universe, where artists become stars, album become continents and a track playing becomes a landscape hiking. The main purpose is to display a different visualization of the music universe, and hopefully get an easier navigation. The system allows to play the selected continents (if the vlc python module is installed and the track is present on the user's file system), to annotate it and to keep track of the journey.

To have further information about installation and requirements, look the Install section.

For the launch options, see the Launch page.

About the music player side: SSD can do a lot of things, even if often not as good as the preexisting music-listening systems. If you only want a powerful and efficient system to just listen to your music, the current version may not be your answer. Nevertheless, some of its features may interest you: like the possibility to keep track of listened songs, or advanced navigation through previously heard songs, or the automatic evaluation of each track by the combination of percentage of listened music and a score based on the focus of the listener. For advanced analysis of the concepts and elements used in SSD, look the Concept index.

The current version, SSD 0.1, is a draft. It contains all the fundamental features needed for the upcoming development, nothing less but nothing more. The point of this alpha version is also to have your feedback and issue report. For advanced feedback, you can send an e-mail to lemni (dot) ze (dot) kat %arobase% gmail (dot) come (without the e at come), and for bug report you can use the convenient tool of gitlab

Many aspects are on construction, and most of the aspects are under-exploited. Many paths begin at this crossroads, but there is not enough time to take them all. So it will be a common task to determine the chosen direction(s), based on the required conception, development and testing time and interest of the feature. To be part of the decisions, you can look at this page: Technological Tree (I hope finding a system to allow votes about feature choices quite soon)

For example a central point would be to make SSD a multiplayer system, to allow the share of comments and impresses on music elements. My dream is to create an open-source software and a common base for international and platform-free environment for music exploration, de-correlated with the actual content of tracks to avoid any copyright issues.

Enjoy your trip in the first effective space opera!

NB: if you are interested in being part of the development crew, the code is open and I will be happy to check your merge request and credit your participation ;)


INSTALL

For the current version, the user has to install modules and languages by himself:
    Python 2.7 (core program)
    Pip (or any way to get the following python modules)
        eyeD3 (metadata reading)
        python-vlc (music playing)

Not mandatory but useful:
    wxPython 2.8 (graphical interface),maybe wx 3 will work (wx is not fundamental but significantly more interesting and practical)
    (for ubuntu: sudo apt-get install python-wxgtk3.0, maybe needed sudo apt install gnome-themes-standard (for kubuntu issues?) )


The program will be able to run with only Python installed with no additional module, but then the only thing you will be able to do is launching the bash version and import a fake system. (and since you can't move the camera in bash version, the interest will be very limited)


LAUNCH

To run SSD, you have to clone the git repository or download a snapshot, then go in the corescoutdriver directory, and run (linux, git required if not via snapshot):

git clone ssh://git@git.afola.ovh:2222/Jeux/SonicScoutDriver.git

cd SonicScoutDriver/corescoutdriver

python LaunchSSD.py

If you are under windows, you can use the cmd with the same commands (but replace / by \ in the path). You can also use a visual file explorer, right clic on the LaunchSSD.py file and select "Open With" -> "Python"

In both cases, the command will run a terminal asking several informations before the first launch. For advanced or regular users, the same informations can be set in the params.py file, in the first paragraph with "advice" informations.


USAGE

How to use SSD?


Exploration

To visually explore local directory.


Requirements


Metadata module (currently eyed3) highly recommanded for this part. Otherwise you will have a poor universe generation
A graphical interface (currently WXpython)
A collection of local .mp3 files (and kinda located at the same place). Otherwise an example pack will soon be available with copyright-free tracks to give an overview of what SSD can do about universe structuring and exploration.



Utilization

TO COME


Music

To navigate through tracks.


Requirements

TO COME


Utilization

TO COME


Tracks

To manipulate individual tracks.


Requirements

TO COME


Utilization

TO COME


Generic approach

In all the cases, the menus are more or less "pilot", "scouting" and "universe".



pilot for flag and journal I/O

scouting for exploration of tracks

universe for library management (load old created universe / import from folder...)



TIPS


SOUND

CAUTION Since this program uses sound output, be careful with the volume of your computer before reaching any land. Volume can easily be lowered (wx: little slider, left to lower ; bash: hit "-" then , will lower by 10 each time)


BACKUPS

DISCLAIMER: Even if all is done to allow a retro and futuro-compatibility, while a stable version is not released, there is no warranty that saved data will be managable by other versions of the SSD (and sometimes even in the same version). The main purpose of the version is currently experimental, so you can begin to scout around and stack data, but don't be too disappointed if you can't get all back in the future...

And regularly do a copy of ssd/ssm files if you don't want to erase your data after a wrong manipulation, since current version writes always in the same files.


FLAGS

Ensure that the song really begins at 0 sec, or define a "Begin" flag, before defining any Interest or Comment Flag, otherwise other landscapes of the same continent may have mispositionned flags.


COMMANDS


Common commands through implementations


m = change metadata for current track, successive fields asked are continent name (track) / planet name (album) / star name (artist). If no change for the current field, just hit  without typing anything. CAUTION: Metadata are effectively changed on local file after all fields have been asked, if a change has been detected. To cancel the current change, type "!X!" in the field
! = reset pilot focus to 100%



WX commands

The possible keys are:


       Tab = change label display (3 modes: full / 1 letter / nothing)
       Space = Change time speed of the universe rotations (2 modes: normal / really slow)
       PageUp = Zoom in
       PageDown = Zoom out
Mouse scroll = zoom
l = show/hide genre color legend


Other actions can be made through buttons and menus


       ! button : left click = pilot focus at 100%, right click = pilot focus freezed at 0%



Sh commands

This section gives specific commands of the terminal interface. These commands are independent from any menu, you can enter them any time (and don't forget to hit enter)


  + = volume + 10
   - = volume - 10
   : = sets begin (or end of flag if begin already defined) for the current landscape at the current position (hit it twice shortly for a punctual flag)
   / = triggers the flag removal menu for the current landscape
   p = pauses the landscape walk (= pause the music player)
   § = freezes the pilot focus at 0 (see Freeze section for detail)



WX Implementation (graphical)

The scouting menu is replaced by the continental toolbar with several buttons.


Tips

If the window freezes without any user action or some controllers disappear, try to resize the window to refresh the elements.

Remember that the window will always freeze when a value is requested in the terminal, for example while changing metadata, defining a flag or manipulating files for save or load. The window will unfreeze as soon as the value is validated.

For some actions (via  or <:> for example, respectively metadata edit and flag positionning), an answer is required in the shell. While the answer is not given, the main graphical window may (and will) become unavailable. This is normal, even if not really clean.

The current continent view has nothing to do with effective track, it is a randomly generated landscape to help localise the position of the rover but can't be related with the music content.


Console Implementation

The console works by a succession of menus, the submenus can be quitted by chosing the option "X".


Tips

The scout driver can be used in the old-fashioned console of a rusty ship: you can navigate through menus by entering the number of the selected item and hitting enter.