ravenscott-rocks/README.md

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
• Installation
• Usage
• SoundCloud Playlist
• Caching
• Routes
• Technologies Used
• Known Issues
• Contributing
• 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:

   git clone https://git.ssh.surf/snxraven/ravenscott-rocks.git
   

2. Navigate to the project directory:

   cd ravenscott-rocks
   

3. Install the dependencies:

   npm install
   

4. Create a cache file for storing track information:

   touch cache.json
   

5. Run the application:

   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:

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

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:

{
  "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: /track/<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.