# Essay 2

In our last essay, we already discussed the product vision of *Beets*. And for this essay, we will dive deeper into the architecture of *Beets*. Starting with the main architectural elements which realize the fundamental properties of *Beets*, we will further give an insight into the components forming the whole *Beets* system, as well as the interactions and connections among them. Finally, we will explore the key attributes and the main API design of *Beets*.

## Main architecture style
*Beets* uses a component-based architectural style for this project[^1]. A component-based architecture style focuses on the decomposition of the design into individual functional or logical components. These components represent well-defined communication interfaces containing methods, events, and properties. For *Beets*, it aims to provide easy modification for the music geeks to add any preferred utilities. So the component-based architecture makes the source code readable and easy to use.

Looking into the source code of *Beets*, we will see two main folders: *Beets* and *Beets plugin*. The *Beets* folder provides the basic music management systems for users. As the primary functionality, the *Beets* folder is not allowed to modify, ensuring the Beets can offer the basic service on any device.

*Beets plugin* provides other functionalities as extra to make the management more accessible and intelligent. This design also allows users to build up the part that they need while not in the folder. This architecture also helps the users to make their contribution to help *Beets* become more powerful.

## Container view
For *beets*, the primary function is written in python, and no other environment is needed to compile its source code. So, the *beets* do not have the container view.

## Components View
As aforementioned, *Beets* is constructed based on a component-based architecture. This section will dive deeper into the components view, which demonstrates the structural decomposition of the software as well as the dependencies between components. The figure *Component View* below shows a components view of *Beets*, which presents the major components as well as the dependencies among them.

In the diagram, we can see that the core of *Beets* consists of five parts, namely Command Line Interface (CLI), configuration file handler, *Beets* utilities (including core functionalities and plugins),autotagger, and database API. The CLI is the visible part of *Beets*, which displays the information to users as well as intake commands from them. The configuration file handler reads and parses the configuration file, and changes the internal configurations (such as the order of the album, the outlook of the user interface) according to users' preferences. The core *Beets* utilities contain the core functionalities such as importing and querying the music library, while the plugins provide more advanced and awesome extensions, including fetching additional data during import and etc. Autotagger provides the capacities of inferring tags based on existing metadata and when there is no available metadata, it can even identify songs from the audio itself via the technology `acoustic fingerprinting`[^2]. Database APIs enable the basic querying, writing, and reading utilities of the music library.

From the figure *Component View* we can clearly see that the components have close dependencies on each other and the external environment. The CLI needs inputs from the user to execute some operations, making it rely on the user. The database API that is responsible for reading and writing data from database needs to check the configuration file to decide in which way the music library should be sorted in the database. Besides, it requires the command from CLI to trigger the `query` and `add_metadata` method. To enable some advanced features, it needs the support of plugins.

To enable acoustic fingerprinting, the autotagger requires the support of low level library `PyGObject`, `FFmpeg`, `chromaprint` and `pyacoustid`[^2]. Besides, the fingerprinting extensions need to be configured in the configuration file. In order to trigger autotagger, the `import` command from CLI is needed. The configuration file handler apparently depends on the content of configuration file.

{{<image file="beets_component_view.png" caption="Component View">}}

## Connectors View
As stated in section *Component view*, the core *Beets* contains five main components, incorporates some low-level libraries, and interact with users and database as well. We can observe the main types of connections used by this project in the image *Connectors View*

Firstly, all the five main components of *Beets* are connected by importing each other in the head of the python file. In this way, they can call the methods in other modules, interact with others and become an organic whole.

Next, the CLI is connected to users through the keyboard and other I/O devices, such that the user is able to input to *Beets* system and get the output from the display.

Additionally, the plugins import lower-level libraries which need to be installed via `pip install` to become available. Thus `pip install` and `import` are the connectors between plugins and libraries.

Finally, the file reader/scanner is another connector that enables the configuration file handler to read the content of the configuration file and adjust the behavior of *Beets* system according to the user preference.

{{<image file="beets_connector_view.png" caption="Connector View">}}

## Development View
Development view of one system means the static organization of source codes and mapping logical view onto codes. There are five main parts for the construction of Beets for development as is shown in the figure ```Organization of Beets Source Codes``` below, namely autotagger, database, user interface, utilities and configuration handler, which realize the main capabilities of Beets. In this part, we will go deep into the overview and interaction of these five main parts.

{{<image file="beets-develop-view.png" caption="Development View">}}

For the part of autotagger, there are three submodules to cooperate, which are `hooks`, `match` and `musicbrainzngs`. This module is functioned to determine the correct metadata for one given file. When doing this, the main module has to import some functions from its submodules, like AlbumInfo in `hooks` to initialize the information of albums.

In the DBcore module, there are four parts to interact and realize the functionalities, which are db, query, query parse and types. This module is functioned to form the basis of Beets' library. When it is time to represent the type information in type module, it will import query module to determine the different ways of query, like StringQuery, SubStringQuery and so forth.

When it comes to the user interface, only one submodule `commands` is included. This submodule' function is to realize the core logic for command-line interface and provide some default commands. This module does not have inner-module interactions and the main interaction happens with other modules, such as autotagger, utilities and so on.

The last part utilities has seven submodules. They are artresizer, bluelet, confit, enumeration, functemplate, hidden and pipeline. This module provides a number of utility functions which mainly depends on some external libraries, like `os`, `fnmatch`, `re` and so forth.

## Run Time View
Since *Beets* is written in Python and there is no need to include any dependencies when running the code to realize the basic functions, we will not cover this part in our essay. But as we mentioned in the previous section, it might the need support of some low level library `yGObject`, `FFmpeg`, `chromaprint` and `pyacoustid`[^2] if users need to use some extended plugins.

## Key Quality Attributes
Flexibility and the ability of user-friendly are the main attributes of Beets. Although it is designed as a library, Beets can do more than that by utilizing a unified plugin interface. This interface allows people to develop Beets plugins in an easy way, by only inherite the interface and overwrite related methods. Therefore, Beets achieves different functions for different target groups.
Besides, Beets is designed for music geeks, who may not familiar with computers. Therefore, Beets has to be easy to use for those people. In fact, ui module in Beets provides a very elegant user-interface. Although the interface is based on the command line, the commands are similar to common Unix commands and are easy to learn and use.

## API Design Principles in Beets

The APIs in *Beets* are in principle all public APIs, due to the property of the *Python* programming language. There is no private method in *Python* and all methods are public methods. However, some APIs are started with a underscore, which in convention represents the private methods in *Python*. This follows the ```Explicit Interfaces Principle```, as public and private APIs can be recognized based on their signature, and can be used to hide unnecessary information from other developers.

While *Beets* supports a large number of plugins, it is actually achieved by a simple interface that is a class named *BeetsPlugin*. This is the base class for all plugins. The developer of the plugins only needs to inherit this class and overwrite all methods in this class. In this way, plugins can be readily developed and used. The design of *BeetsPlugin* fits the ```Small Interfaces Principle```, as it balances usability and reusability.

Besides the aforementioned 2 principles *Beets*'s APIs have followed, they also follow the ```Clear Interfaces Principle```. The names of APIs are easy to understand and clearly shows the purpose of the function or class. For example, in the *BeetsPlugins* class, there are several virtual methods that need to be overwritten. The names of these methods are very clear, like the *commands* method returns a list of commands that should be added to the *Beets*'s CLI, and the *album_distance* and the *track_distance* add distance for all alum-level and track comparison. Although users are not directly exposed to these APIs since they mainly use the CLI, these clear APIs help the developers to understand and use them, which further develops the *Beets* community.

The ```Principle of Least Surprise``` is applied to the CLI design. The commands in CLI is very intuitive to use as it fits the users' expectations. Take the *ls* command as an example, this command is used to list all the files and folders in a directory in UNIX-like system. In *Beets*, it can be used to list all albums and collections. It can also be used with a query string, and this will return a list of songs that meet the query. They demonstrate that users can easily understand the CLI of *Beets* and this meets the definition of ```Principle of Least Surprise```.

## References

[^1]: https://en.wikipedia.org/wiki/Component-based_software_engineering
[^2]: https://beets.readthedocs.io/en/stable/plugins/index.html#autotagger-extensions

<!-- <div id="refer-anchor-1"></div>

- [1][Component-based software engineering](https://en.wikipedia.org/wiki/Component-based_software_engineering)

<div id="refer-anchor-2"></div>

- [2][Autotagger Extensions](https://beets.readthedocs.io/en/stable/plugins/index.html#autotagger-extensions)

<div id="refer-anchor-3"></div>

- [3][Chromaprint/Acoustid Plugin](https://beets.readthedocs.io/en/stable/plugins/index.html#autotagger-extensions) -->