From 1feebfbadd5de5801319dd5ffbf18e5919331f21 Mon Sep 17 00:00:00 2001 From: Lars Noack Date: Tue, 7 May 2024 11:03:09 +0200 Subject: [PATCH] feat: added contribute --- contribute.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 contribute.md diff --git a/contribute.md b/contribute.md new file mode 100644 index 0000000..5609b85 --- /dev/null +++ b/contribute.md @@ -0,0 +1,64 @@ +# How to contribute + +I am always happy about pull requests. + +If something is missing, like attributes for an object feel free to either add it yourself or open an issue, if you choose to just change it, it might be changed back in the review process. + +So here are some things you can do to help out: + +1. [implement a new page like e.g. SoundCloud](#add-a-new-page) +2. look at [open issues](https://gitea.elara.ws/music-kraken/music-kraken-core/issues) or look at any of the [project board]s(https://gitea.elara.ws/music-kraken/music-kraken-core/projects) for open tasks. + +> Before you start, please make sure to at least read the [core concepts to prevent misunderstandings](overview.md). + +## Add a new Page + +Every scraping code is encapsulated in a child class of the `Page` class. + +You need to implement the following functions: + +### Search and url functions + +- `get_source_type` This function should return the type of the object type, the source was passed into. +- `general_search` This function returns a list of data objects, found with a simple query. Only implement the following functions if the page allows advanced search: + - `song_search` returns a list of `Song` objects. + - `album_search` returns a list of `Album` objects. + - `artist_search` returns a list of `Artist` objects. + - `label_search` returns a list of `Label` objects. + +### Fetch functions + +These functions all take a `Source` object as input and return a more detailed object. It gets automatically merged with the other existing objects. + +- `fetch_song` +- `fetch_album` +- `fetch_artist` +- `fetch_label` + +If the page that is scraped does not have for example labels, just don't implement the functions for `Label`. + +### downloading + +The function to actually download something is `download_song_to_target`. Its arguments are `source`, `target` and `desc`. If you want to remove certain intervals from the song, you can return a list of the intervals in the function `get_skip_intervals`. + +### Step by step guide + +1. Just create a new file with the name `your_page.py` +in the [page module](src/music_kraken/pages). +1. Then you can simply copy the contents of the [preset](src/music_kraken/pages/preset.py) over to your file. +2. All the functions you need to implement, can be found in the [preset](src/music_kraken/pages/preset.py). + +### Important notes + +- There is no need to check if you for example added a source of a song twice. I do much post-processing to the data you scrape in the page classes. You can see what exactly I do in [abstract.py](src/music_kraken/pages/abstract.py). +- Use the connection class how it is laid out in the preset to make the request. This will take care of retrying requests, rotating proxies, consistent use of tor (if selected in the config). You have: + - `connection.get()` + - `connection.post()` + +--- + +music-kraken logo + +To get help, or to let me know on what you are working, just write in the development room of our matrix space what you are currently doing, and if you need help. I will try to help you as soon as possible. + +**Click [this invitation](https://matrix.to/#/#music-kraken:matrix.org) _([https://matrix.to/#/#music-kraken:matrix.org](https://matrix.to/#/#music-kraken:matrix.org))_ to join our matrix room.** \ No newline at end of file