search

marcuswhybrow / ray-peat-rodeo

Ray Peat interviews transcribed & augmented
https://raypeat.rodeo/
8 stars 1 forks source link
bash direnv github-deployment github-pages go-templ golang markdown markdown-plugin nix nix-flake openai-whisper ray-peat static-site-generator tailwindcss

readme

raypeat.rodeo is the open-source effort to transcribe the public works of Ray Peat.

Deploy to GitHub Pages Built with Nix

banner

Getting Started

Get Nix Package Manager, then clone this repository and start the auto-reloading dev server:

git clone git@github.com:marcuswhybrow/ray-peat-rodeo.git
cd ray-peat-rodeo
nix develop -c modd

Those are the main things, and editing any of them trigger the dev server to auto reload, and your browser should hot-load the changes and auto refresh, making a near instant dev cycle.

And finally, you may wish to use direnv and nix-direnv to automatically load all project dependencies and tools into your shell environment whilst you are inside the project directory (auto unloads when you leave it). In the project directory:

direnv allow

Project Goals

  1. Round up every Ray Peat interview, article, newsletter and book.
  2. Use AI to quickly transcribe interviews.
  3. Store each interview (etc.) as human readable markdown.
  4. Generate a website from those markdown source files.
  5. Site-wide search of all assets.
  6. Tooltips for all mentioned topics and people linking to all other mentions.
  7. Timestamps linking to specific times in original audio or video.
  8. Sidenote annotations for clarifications and issues to be resolved.

What this amounts to is using AI to quickly transcribe all interviews, then storing the results in markdown. Next, one improves and augments each markdown file with corrections, formatting and tagging all mentions and timecodes.

Formatting is part of the markdown standard, but what I'm calling "mentions", "timecodes", and "issues" are extensions to the markdown syntax written specifically for this project. With custom markdown syntax any functionality can be realised whilst keeping the markdown documents human readible for archival purposes, and portability to other projects.

Adding Interviews

Go to ./assets. Every file in this directory is a Markdown file. Each one repesenting a unique Ray Peat interview. Each filename is formatted in Kebab Case and begins with the date as YYYY-MM-DD (ISO 8601 format) followed by the title of the interview.

Ray Peat Rodeo will respect whatever date is declared in the file name, and use it across the website. The title portion, verbatim, becomes the URL at which this interview will exist.

For example...

touch ./assets/2008-07-02-an-example.md

... will become a web page accessible at raypeat.rodeo/an-example/ and will appear in the 2008 section, as having taken place on July 2nd. The contents of the file must begin with the following YAML frontmatter.

---
source:
    series: The name of the show Ray is appearing on 
    title: Human readable title (similar to filename title but more flexible)
    url: https://example.com/the-original-audio-or-video
    kind: audio
---

Done. Next one may use the transcribe tool to automatically add an AI transcription to this file (see AI Transcription).

AI Transcription

flake.nix packages a bash script named transcribe. It downloads the source audio of any file in ./assets/todo, transcribes it, then updates the asset with the transcription, and updates the frontmatter data to reflect this change.

  1. Argument #1 is the markdown file to transcribe and update.
  2. Argument #2 is your name, to log in the assets metadata.
nix run github:marcuswhybrow/ray-peat-rodeo#transcribe -- ./assets/todo/2024-10-12-example.md "Marcus Whybrow"

Done. Once you've added the AI transcript it's contents will be available to the site-wide search engine, helping readers to further explore Ray's ideas. Finally, and optionally, one may augment the transcript with special formatting to take it to the next level (see Augmenting and Completing A Transcript).

Augmenting and Completing A Transcript

Who's Speaking?

Prefixing sentences with the speakers initials when the speaker changes, such as RP: for Ray Peat, allows Ray Peat Rodeo to separate the transcript into different speach bubbles.

Make sure to define the full name for each initials used in the YAML frontmatter at the top of the markdown file like so:

---
speakers:
    RP: Ray Peat
    MW: Marcus Whybrow
---

MW: Hi Ray, how are you?

RP: Very good, thank you.

What Time Is It?

Interspersing timestamps within the transcript, such as [12:34], allows readers to jump staight to that point in the original source audio or video. I like to use timestamps sparingly to indicate a change in topic or a new question being asked. For example...

MW: That's great. [12:34] And what do you think about that, Ray?

RP: I think...

Tip: Timestamps can express hours too: [2:01:12]

Mentions

When a person, topic, chemical, hormone, book, website, or any thing is mentioned, marking it as a "mention" gives readers a little popup bubble that provides a mini summary of where else it's been discussed. Surround the mentioned thing in double square bracets like this...

RP: The history of [[Estrogen]] reesearch...

For mentioned people, put their surname first, then a comma, then their given names (without titles such as Sir or Doctor). For example...

MW: [[Wodehouse, Pelham Grenville]] was the creater of Jeeves and Wooster...

This backwards convension helps Ray Peat Rodeo know how to order every mention alphabetically. RPR is smart enough to output the name the right way around to the reader...

Pelham Grenville Wodehouse was the creator of Jeeves and Wooster...

Note: The first comma always has this effect. Commas must be otherwise avoided in mention names.

To tailor the displayed text to your liking use the | character...

MW: I've been reading [[Blake, William|an author]] that...

Which becomes...

I've been reading an author that...

And finally, you can associate books with their authors using the > character. For example...

MW: and I discovered he wrote [[Blake, William > Jerusalem]] around then...

Jerusalem is known as a "sub mention", and it'll be included included in the popup summary for William Blake, and vise versa. Sub mentions are a powereful way to help new readers explore Ray's influences by hopping around these associations bound together via unique conversations.

Tip: A mention or submention may be a URL or email address. In these speacial cases, the popup summary will also contain a direct link to the URL, or a "mailto" link to open the reader's email client directly.

Tip: Mentioning a scientific paper by it's DOI URL (https://doi.org/...) automatically grabs the papers full title from the DOI database to display to the reader. See this real example.

Is That Clear?

When someone new to Ray Peat may not understand a reference or term, one can add a sidenote, using curly brackets, that appears distinct from the main text in a little bubble. For example...

RP: PUFA {Polyunsaturated Fats} were originally...

I like to clarify a term this way the first time it's used in a transcript, then trust the reader to recall it's definition, or refer back to it. This serves to keep interruptions to a minimum and let Ray take center stage.

Huh?

Sometimes Ray's mentions are ambiguous, or the full name of a paper or person is unclear. In this case one may
create an issue in the GitHub project and title it as a question to which others may know the answer. For example "Which 1986 biology paper is Ray refering to?" Add to the issue's description any pertenant context and submit the issue.

Once created, take note of the issue's unique numerical ID displayed near the issue's title. Refer to this ID using a # inside of a sidenote:

RP: In 1986 they showed {#51} that even though...

When a sidenote contains a # and a number, a golden, call to action, issue bubble containing the issue title will be shown to readers. In this case the bubble will read "#51 Which 1986 biology paper is Ray refering to?" Clicking the bubble takes readers to the GitHub issue itself.

GitHub issues are a great way to keep track of opportunities for improving the clarity of readability for new readers, and serve to invite and organise the expertese of those who might fill in the gaps.

I like to use issues liberally. If I'm unsure of a mention, or don't know how to word a sidenote, I create an issue and move on. This keeps transcription fluent, leaving future me, or someone better educated, to fix the issue later.

Similar Projects

Open an issue if I've missed a similar project.

Cheers

At the momemt I'm just one Marcus working on Ray Peat Rodeo; chugging along in my spare time. Thanks for your interest in the project, even if you can't help out with the code. Go on, give the project a star! 😉

If you want to sponsor my work see my GitHub sponsors page.

Cheers,
Marcus