Youtamp

See Light Theme

A simple web application for YouTube timestamp creation.

Development

Follow these steps to set up and run the project in your local development environment.

Prerequisites

• Python (version 3.12 or higher recommended)
• uv (a fast Python package installer and resolver)

In case you want to edit frontend (JavaScript/CSS/HTML), install the following additionally:

• Node.js (version 16 or higher recommended)
• npm (comes with Node.js)

Installation

Clone the repository:

git clone https://github.com/Onyx-Nostalgia/youtamp.git
cd youtamp

Running the Development Server

1. Create your environment file: Copy the example environment file to create your own local configuration.

   cp .env.example .env

2. Configure Environment Variables: Open the .env file and add your GEMINI_API_KEY. See the Environment Variables (.env) section below for more details on all available options.

3. Start the Flask development server:

   uv run app.py

4. Open the browser: Navigate to http://127.0.0.1:45334/

5. (Optional) For Frontend Development: If you need to edit CSS files, run the following command in a separate terminal. It will watch for changes in static/css/input.css and rebuild automatically.

   npm run dev.build:css

Environment Variables (.env)

The .env file is used to configure the application. Below is a description of each variable found in the .env.example file.

Variable	Description	Default
GEMINI_API_KEY	(Required) Your API key for the Gemini service. You can get one from Google AI Studio.	""
LOG_LEVEL	Sets the application's logging verbosity.	INFO
MOCK_FILE	For frontend testing. If a path to a text file is provided (e.g., artifacts/video_id/timestamps.txt), the app will return the content of that file instead of calling the Gemini API.	""
HTML_FILE	Specifies which HTML file in the templates/ directory to render.	index.html
SAVE_PROMPT	If true, saves the generated prompt to a file in the artifacts/ directory for debugging.	false
SAVE_RESPONSE	If true, saves the raw response from the Gemini API to a file in the artifacts/ directory.	false
LOAD_PROMPT	If true, loads a previously saved prompt from the artifacts/ directory, bypassing transcript fetching. Useful for quickly re-running a prompt.	false

Note

If you have GEMINI_API_KEY already configured as a system-wide environment variable (e.g., in your .zshrc or .bashrc), you do not need to set it again in the .env file, as the application will automatically use the existing key.

How to edit frontend files (JavaScript/CSS/HTML)

Frontend base on DaisyUI and TailwindCSS framework.

1. Edit files in the static/ directory
   • JavaScript files: static/app.js
   • CSS files: static/css/input.css
   • if you want to add new files, just create them in the static/ folder
2. Edit template/index.html for HTML structure.
3. Refresh your browser to see changes.

Linting & Formatting

We use Ruff to maintain code quality and a consistent style.

Check for issues: The following commands will report any issues without modifying files.

# Check for formatting issues
uvx ruff format --check .

# Check for linting errors
uvx ruff check .

# Check for type errors
uvx --with pydantic --with flask mypy .

Apply fixes: The following commands will automatically format the code and fix any fixable linting issues (like removing unused imports).

# Automatically format all files
uvx ruff format .

# Automatically fix linting issues
uvx ruff check . --extend-fixable F401 --fix

Note

While Ruff can fix many issues automatically, some may require manual changes.