# 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/tracks/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.