149 lines
5.0 KiB
Markdown
149 lines
5.0 KiB
Markdown
# Raven Scott Metal Site
|
|
|
|
Welcome to the **Raven Scott Metal Site**, a dynamic and metal-inspired web application that lists and showcases SoundCloud tracks from the playlist "Raven Scott Metal." The site is designed using **Bootstrap 4** and features a dark, edgy design tailored to a metal aesthetic. Each track is displayed with a SoundCloud player, with links to detailed pages for each individual track.
|
|
|
|
## Table of Contents
|
|
- [Features](#features)
|
|
- [Installation](#installation)
|
|
- [Usage](#usage)
|
|
- [SoundCloud Playlist](#soundcloud-playlist)
|
|
- [Caching](#caching)
|
|
- [Routes](#routes)
|
|
- [Technologies Used](#technologies-used)
|
|
- [Known Issues](#known-issues)
|
|
- [Contributing](#contributing)
|
|
- [License](#license)
|
|
|
|
## Features
|
|
- Displays all tracks from the "Raven Scott Metal" SoundCloud playlist.
|
|
- Dynamic slug-based routes for each track.
|
|
- Sorts tracks by the number of plays, followed by publication date.
|
|
- Embeds SoundCloud players for each track.
|
|
- Caching system to prevent fetching the playlist too frequently.
|
|
- Bootstrap 4 responsive design with a dark metal theme.
|
|
- Fallback message if a track doesn't have a description.
|
|
- Easy-to-use interface with individual pages for each track.
|
|
|
|
## Installation
|
|
|
|
To get started with the Raven Scott Metal site locally, follow these steps:
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://git.ssh.surf/snxraven/ravenscott-rocks.git
|
|
```
|
|
|
|
2. Navigate to the project directory:
|
|
```bash
|
|
cd ravenscott-rocks
|
|
```
|
|
|
|
3. Install the dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
4. Create a cache file for storing track information:
|
|
```bash
|
|
touch cache.json
|
|
```
|
|
|
|
5. Run the application:
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
6. Open your browser and navigate to `http://localhost:3000`.
|
|
|
|
## Usage
|
|
|
|
### Fetching Playlist Data
|
|
The site uses the **SoundCloud Scraper** to fetch playlist data. By default, the playlist is only fetched once a week and cached in `cache.json`. You can force a fresh fetch using the `--fetch` flag:
|
|
|
|
```bash
|
|
npm start -- --fetch
|
|
```
|
|
|
|
### Viewing Tracks
|
|
The homepage lists all tracks from the "Raven Scott Metal" playlist. Each track has its own card displaying the following information:
|
|
- Title of the track
|
|
- Short description (or a fallback message if no description is available)
|
|
- Embedded SoundCloud player
|
|
|
|
### Track Pages
|
|
Each track has a dedicated page with its own URL based on a slug generated from the track title. The URL format is:
|
|
```
|
|
http://localhost:3000/tracks/<track-slug>
|
|
```
|
|
|
|
On each track page, you'll find:
|
|
- The track title
|
|
- The full description of the track (if available), rendered with line breaks
|
|
- An embedded SoundCloud player to listen to the track
|
|
|
|
## SoundCloud Playlist
|
|
|
|
The site fetches tracks from the following SoundCloud playlist:
|
|
- **Playlist URL:** [Raven Scott Metal](https://soundcloud.com/snxraven/sets/raven-scott-metal)
|
|
|
|
Each track is fetched and displayed in order of play count (most played first), and then by the publication date.
|
|
|
|
## Caching
|
|
|
|
The site uses a caching mechanism to reduce the number of requests to the SoundCloud API. The cache stores:
|
|
- A list of tracks from the SoundCloud playlist
|
|
- The timestamp of the last time the playlist was fetched
|
|
|
|
By default, the cache is valid for 7 days. After that, the playlist will be fetched again. If you want to force a refresh of the playlist before the cache expires, run the app with the `--fetch` flag.
|
|
|
|
### Cache Structure
|
|
The cache is stored in `cache.json` and looks like this:
|
|
```json
|
|
{
|
|
"tracks": [
|
|
{
|
|
"title": "Ebon Shroud",
|
|
"description": "A chilling, shadowy realm...",
|
|
"url": "https://soundcloud.com/snxraven/ebon-shroud",
|
|
"playCount": 323,
|
|
"publishedAt": "2024-07-31T07:26:51.000Z",
|
|
"slug": "ebon-shroud"
|
|
},
|
|
...
|
|
],
|
|
"timestamp": 1729150557891
|
|
}
|
|
```
|
|
|
|
## Routes
|
|
|
|
### Home Page
|
|
- **URL:** `/`
|
|
- **Description:** Lists all tracks from the "Raven Scott Metal" playlist. Tracks are sorted by play count and then by publication date. Each track is displayed in a card with a link to the track page.
|
|
|
|
### Track Pages
|
|
- **URL Format:** `/tracks/<track-slug>`
|
|
- **Description:** Displays detailed information about a specific track, including its full description and an embedded SoundCloud player.
|
|
|
|
### Example Track URL
|
|
```
|
|
http://localhost:3000/track/ebon-shroud
|
|
```
|
|
|
|
## Technologies Used
|
|
|
|
### Backend
|
|
- **Node.js**: JavaScript runtime for the server.
|
|
- **Express.js**: Web framework for building the server-side application.
|
|
- **SoundCloud Scraper**: Library for fetching SoundCloud playlist and track data.
|
|
- **EJS**: Templating engine for rendering HTML views.
|
|
- **Bootstrap 4**: Frontend CSS framework for responsive design.
|
|
|
|
### Frontend
|
|
- **Bootstrap 4**: Used for styling the site with a responsive, mobile-first design.
|
|
- **Custom Styles**: Added custom styles for a dark metal theme.
|
|
|
|
## Known Issues
|
|
- SoundCloud API rate limits may affect data fetching if too many requests are made in a short period.
|
|
- If a track doesn't have a description, the fallback message is displayed. However, some descriptions may not render properly if they contain unusual formatting.
|