DaPlayer

Note: This document will guide you through the process of contributing to DaPlayer’s code base. However, it just concerns the main repository (i.e. the player’s interface and logic).

If you are willing to work on translations or the tagging system, please checkout these projects:

daplayer/i18n

daplayer/tagging

DaPlayer is an open source piece of software which is released under the AGPL-3.0 license. If you don’t want to read the whole license, in a nutshell, it means that you can edit the source code for your personal needs but if you distribute the software, you need to make the source code available even if you use the code for a web application/service.

Warning: Maintaining open source softwares is hard ! Unfortunately, I can't guarantee you that your feature will be accepted because of a lot of reasons including :

Maintenance cost
Consistency
Usability
Specificness

Thus, feel free to open a ticket on the tracker to discuss about your feature first ! ❤️

Software Requirements

To be able to write a patch or improve something in DaPlayer, you should have the following installed on your computer:

Node (v6.3+)
Yarn
A C++ compiler (GCC or Clang)
Make
Git

Knowledge Requirements

This document will guide you throughout the process of creating a patch for DaPlayer but you’ll need to have certain knowledges to be able to do so. You should be able to:

Work with HTML & CSS (LESS)
Write JavaScript (ECMAScript 2015) code
- Having knowledge of asynchronous execution
- and being able to use Promises (all the code rely on them).

Clone the Git repository

The source code of the project is available on GitHub:

$ git clone https://github.com/daplayer/daplayer
$ cd daplayer

Then you can install the dependencies:

$ make install

You can run the application with:

$ yarn start

Then, you can create a new Git branch to host your changes and check it out:

$ git checkout -b my-new-feature

The folder structure

DaPlayer is written with vanilla JavaScript which implies that it has a pretty peculiar folder structure.

The `main.js` file

This project is based on Electron. This file is the entry point of the application. It requires the different Electron APIs and then load the index page. The software is just a Single Page Application; everything happens on the same page but anytime a link is clicked, we just change the content of the page to display the requested content.

The `index.html` file

This file simply contains the application’s skeleton; the JavaScript entry point is the assets/javascripts/bootstrap.js file that handles a lot of things when the application boots up. The different sections (e.g. the sidebar) are filled in through the Ui#loadPartials function.

The `app/` folder

The app/ folder contains some folders:

Folder	Description
base/	Contains some base classes extended elsewhere.
services/	Contains services used application-wide.
ui/	Contains classes representing a specific UI section.
views/	Partials used application-wide.

This folder also contains some common classes that can be useful throughout the application:

File	Description
analytics.js	Handles analytics inside the application
application.js	Application wide logic; dead simple at the moment
cache.js	Static class managing caching.
config.js	Static class managing the user's configuration (mostly a wrapper around `localStorage`).
core_ext.js	Contains some extensions for native object's prototype like `String#includes` or `Array#first`.
credentials.js	Class managing all the credentials (i.e. the registered applications' credentials for SoundCloud and YouTube and the user's ones).
database.js	A wrapper arround indexedDB (used to store analytics).
downloads.js	Class that globally manages the downloads.
file_picker.js	Wrapper around the Electron's dialog API ; dead simple at the moment.
helpers.js	Handlebars helpers used application-wide.
html.js	Utility class to generate HTML tags.
initializer.js	File that loads most of our dependencies and objects.
jquery_ext.js	Some jQuery extensions to simplify the code.
mappers.js	Glob constant shortcuts (e.g. `Service.for('soundcloud')`
menu.js	File that sets the application's menu (using the Electron API).
notification.js	Tiny class that manages notifications inside and outside the application.
paths.js	Static class to deal with paths.
player.js	Static class managing the player logic.
queue.js	Static class managing the playing queue.
router.js	Router class to correctly dispatch some h-refs.
sub_window.js	Wrapper around Electron's `BrowserWindow` to manage sub windows inside the application.
timing.js	Timing related functions.
ui.js	Tote bag for common user-interface-related actions (e.g. display a loader waiting for data to be loaded).
view.js	Static class that compiles and renders HandleBars views.

The `assets/` folder

The assets folder is composed of 5 different sub-folders:

Folder	Description
fonts/	The fonts used in the application.
icons/	The application’s icons.
images/	The images used inside the application.
javascripts/	Contains `bootstrap.js` which is defining our event handlers.
stylesheets/	All the LESS stylesheets.

Module’s folder structure

Each module (i.e. local, meta, soundcloud, youtube) is stored in its own folder but these folders all have the same structure which is basically a classic MVC (Model-View-Controller) pattern.

File	Description
views/	Contains the HandleBars views.
client.js	Abstraction class to deal with API calls (SoundCloud and YouTube only).
controller.js	The controller class which contains actions. Each action roughly load data from the model and render a view passing the data.
helpers.js	HandleBars helpers that are used inside the views (meta and app only).
model.js	Abstraction class to fetch data (either tied to a service or the file system).
player.js	Handles callback registration for the service’s medias.
service.js	Abstraction class to manage connection, authorization and some stuff specific to the service (e.g. downloading).

The `test/` folder

This folder contains different sub-folders that all contains tests for different parts of the software.

test/helpers: to test HandleBars helpers.
test/integration: to test the correctness of a feature at the user level.
test/models: to test model-specific logic.
test/unit: to test classes stored under app/.
test/views: some integrity tests for the views to ensure that we aren’t using missing stuff. You normally shouldn’t care about this folder.

Tests are run through Mocha; to write a test, you just need to tell Mocha which object/feature you are testing with the describe function and describe what each test is doing by passing a string to the it function. For instance:

require('../test_helper');

describe('MyAwesomeClass', () => {
  describe('#method', () => {
    it('should be awesome', () => {
      assert(MyAwesomeClass.isAwesome());
    });
  });
});

Next Step

Now that you have a local copy of the source code and that you know how it is organized, you can go ahead and do a change to the code base like fixing a bug or adding a feature that you want !

Sending a Pull Request

If you are willing to send a pull request to make your change available directly in DaPlayer, you’ll need to make sure that your patch is looking good and that all the tests are passing. To run the tests, you can run:

$ make test

Then, if everything is fine, you should commit your changes in Git:

$ git add .
$ git commit

Make sure that you wrote a good commit message, then you can fork DaPlayer on GitHub and change the remote source of the repository to your fork, then push your changes:

$ git remote remove origin
$ git remote add origin https://github.com/[Your GitHub handle]/daplayer
$ git push origin my-new-feature

Finally, open your GitHub repository in the browser and click on the “Create Pull Request” link.

Contributing