Transcript Parser - Complete Installation Guide

Overview

This guide provides step-by-step instructions for setting up a fresh machine to download, build, and run the Transcript Parser project from GitHub. Follow these instructions in order to ensure a successful setup.

System Requirements
Install Prerequisites
Clone the Repository
Project Setup
Configure Environment
Build the Application
Run the Application
Verify Installation
Troubleshooting

System Requirements

Minimum Requirements

Operating System: Windows 10+, macOS 10.13+, or Ubuntu 18.04+
RAM: 4GB (8GB recommended)
Disk Space: 2GB free space (for tools, dependencies, and project)
Internet Connection: Required for downloading dependencies and API calls

Install Prerequisites

Step 1: Install Node.js

Node.js is required to run the application and manage dependencies.

Windows

Visit nodejs.org
Download the LTS (Long Term Support) version (currently v18 or higher)
Run the installer (node-vXX.X.X-x64.msi)
Follow the installation wizard:
- Accept the license agreement
- Choose installation path (default: C:\Program Files\nodejs\)
- IMPORTANT: Check the box that says "Automatically install necessary tools" (installs Python and Visual Studio Build Tools)
Click "Install" and wait for completion
Restart your computer

macOS

Option 1: Using Official Installer

Visit nodejs.org
Download the LTS version for macOS
Run the .pkg installer and follow the prompts

Option 2: Using Homebrew (recommended if you have Homebrew)

brew install node

Linux (Ubuntu/Debian)

# Update package index
sudo apt update

# Install Node.js LTS using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

Verify Node.js Installation

Open a terminal/command prompt and run:

node --version
# Should output: v18.X.X or higher

npm --version
# Should output: 9.X.X or higher

Step 2: Install Git

Git is required to clone the repository from GitHub.

Windows

Visit git-scm.com
Download the latest version for Windows
Run the installer (Git-X.XX.X-64-bit.exe)
Follow the installation wizard with these recommended settings:
- Select Components: Keep defaults (Git Bash, Git GUI)
- Default Editor: Choose your preferred editor (VS Code recommended)
- Adjusting PATH: Select "Git from the command line and also from 3rd-party software"
- Line Ending: Select "Checkout Windows-style, commit Unix-style"
- Terminal Emulator: Use MinTTY (default)
- Git Pull Behavior: Default (fast-forward or merge)
Click "Install" and wait for completion

macOS

Option 1: Using Official Installer

Visit git-scm.com
Download and run the installer

Option 2: Using Homebrew (recommended)

brew install git

Option 3: Using Xcode Command Line Tools

xcode-select --install

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install git -y

Verify Git Installation

git --version
# Should output: git version 2.XX.X or higher

Configure Git (First Time Setup)

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Step 3: Install a Code Editor (Optional but Recommended)

Visual Studio Code (Recommended)

Visit code.visualstudio.com
Download the installer for your operating system
Run the installer:
- Windows: Run the .exe installer
- macOS: Drag VS Code to Applications folder
- Linux: Use .deb or .rpm package, or Snap

Recommended VS Code Extensions:

ESLint (dbaeumer.vscode-eslint)
Prettier - Code formatter (esbenp.prettier-vscode)
TypeScript Vue Plugin (Vue.vscode-typescript-vue-plugin)
Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)

Alternative Editors

JetBrains WebStorm: jetbrains.com/webstorm
Sublime Text: sublimetext.com
Atom: atom.io

Step 4: Install Python (Windows Only - for native dependencies)

Some npm packages require Python for building native modules.

Windows

Visit python.org
Download Python 3.11 or higher
Run the installer
IMPORTANT: Check the box "Add Python to PATH"
Click "Install Now"

Verify:

python --version
# Should output: Python 3.11.X or higher

Note: If you installed Node.js with "Automatically install necessary tools" checked, Python should already be installed.

macOS/Linux

Python usually comes pre-installed. Verify:

python3 --version

Clone the Repository

Step 1: Choose a Project Directory

Decide where you want to store the project. For example:

Windows: C:\code\ or C:\Users\YourName\Projects\
macOS/Linux: ~/code/ or ~/Projects/

Step 2: Open Terminal/Command Prompt

Windows: Press Win + R, type cmd, press Enter
macOS: Press Cmd + Space, type Terminal, press Enter
Linux: Press Ctrl + Alt + T

Step 3: Navigate to Your Project Directory

# Windows
cd C:\code

# macOS/Linux
cd ~/code

If the directory doesn't exist, create it:

# Windows
mkdir C:\code
cd C:\code

# macOS/Linux
mkdir ~/code
cd ~/code

Step 4: Clone the Repository

git clone https://github.com/KevenWMarkham/transcript-parser.git

This will create a transcript-parser folder with all project files.

Step 5: Navigate into the Project

cd transcript-parser

Project Setup

Step 1: Install Project Dependencies

Run the following command to install all required npm packages:

npm install

What this does:

Downloads all dependencies listed in package.json
Installs both production and development dependencies
Sets up Husky git hooks automatically
May take 2-5 minutes depending on your internet speed

Expected output:

added XXX packages in XXs

Step 2: Install Playwright Browsers (for End-to-End Testing)

npx playwright install

What this does:

Downloads Chromium, Firefox, and WebKit browsers for testing
Required for running E2E tests
Takes about 200-300MB of disk space

Configure Environment

Step 1: Obtain Google Gemini API Key

The application requires a Google Gemini API key for transcription functionality.

Visit Google AI Studio
Sign in with your Google account
Click "Create API Key"
Copy the generated API key (starts with AIza...)

Important: Keep this key secure and never commit it to git.

Step 2: Create Environment File

In the project root directory (transcript-parser), create a new file named .env:

Windows (Command Prompt)

type nul > .env
notepad .env

Windows (PowerShell)

New-Item -Path .env -ItemType File
notepad .env

macOS/Linux

touch .env
nano .env

Step 3: Add API Key to .env File

Paste the following into the .env file:

# Google Gemini API Key (Required for transcription)
VITE_GEMINI_API_KEY=your_api_key_here

# Optional: Database configuration (for future features)
# DATABASE_URL=postgresql://user:password@localhost:5432/transcript_db

Replace your_api_key_here with your actual API key.

Example:

VITE_GEMINI_API_KEY=AIzaSyDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Save and close the file:

Notepad: File → Save, then close
Nano: Press Ctrl + O, then Enter to save, Ctrl + X to exit

Step 4: Verify .env File

Check that the file was created correctly:

# Windows
type .env

# macOS/Linux
cat .env

You should see your API key displayed.

Build the Application

Step 1: Build for Development (Quick Test)

To verify everything is set up correctly, run the development server:

npm run dev

Expected output:

VITE vX.X.X  ready in XXX ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

What this does:

Starts the Vite development server
Enables Hot Module Replacement (HMR) for live updates
Opens the app at http://localhost:5173

Open a web browser and visit http://localhost:5173 to see the app running.

Press Ctrl + C in the terminal to stop the server.

Step 2: Build for Production

To create an optimized production build:

npm run build

Expected output:

vite v6.0.5 building for production...
✓ XXX modules transformed.
dist/index.html                   X.XX kB │ gzip: X.XX kB
dist/assets/index-XXXXX.js      XXX.XX kB │ gzip: XXX.XX kB
✓ built in XXXs

What this does:

Runs TypeScript compiler to check for type errors
Creates optimized production bundle in dist/ folder
Minifies JavaScript and CSS
Ready for deployment or Electron packaging

Step 3: Build Electron Application (Desktop App)

To build the desktop application:

Windows

npm run electron:build:win

Expected output:

• electron-builder  version=XX.X.XX
• loaded configuration  file=package.json ("build" field)
• building        target=nsis file=dist\Transcript Parser Setup X.X.X.exe
• building block map  blockMapFile=dist\Transcript Parser Setup X.X.X.exe.blockmap

The installer will be created in the dist/ folder:

Transcript Parser Setup X.X.X.exe - Installer
Transcript Parser X.X.X.exe - Portable version

macOS

npm run electron:build:mac

Output: .dmg file in dist/ folder

Linux

npm run electron:build:linux

Output: .AppImage or .deb file in dist/ folder

Build Time: First build may take 5-10 minutes. Subsequent builds are faster.

Run the Application

Option 1: Development Mode (Web Browser)

Best for development and testing:

npm run dev

Open browser to http://localhost:5173

Features:

Hot reload on file changes
Source maps for debugging
Fast refresh

Option 2: Electron Development Mode (Desktop App)

Run the app as a desktop application during development:

npm run electron:dev

What this does:

Starts Vite dev server
Waits for server to be ready
Launches Electron app pointing to dev server

Features:

Desktop app experience
DevTools available (Ctrl+Shift+I)
Live reload on changes

Option 3: Production Build (Web)

Preview the production build locally:

npm run preview

Opens at http://localhost:4173 (or next available port)

Option 4: Installed Electron App

After building with npm run electron:build:win, run the installer:

Windows:

Navigate to dist/ folder
Run Transcript Parser Setup X.X.X.exe
Follow installation wizard
Launch from Start Menu

macOS:

Open the .dmg file
Drag app to Applications
Launch from Applications

Linux:

# AppImage
chmod +x dist/Transcript\ Parser-X.X.X.AppImage
./dist/Transcript\ Parser-X.X.X.AppImage

# .deb package
sudo dpkg -i dist/transcript-parser_X.X.X_amd64.deb

Verify Installation

Test 1: Check Development Server

npm run dev

✅ Success: Browser opens to http://localhost:5173 and shows the app

Test 2: Load Demo Transcript

In the running app, click "🎬 Load Sprint 4 Demo (60 Entries)" button
Verify:
- ✅ 60 transcript entries load
- ✅ Speaker summary panel shows 3 speakers
- ✅ Smooth scrolling works
- ✅ Color-coded speaker badges appear

Test 3: Run Tests

npm test

✅ Success: All tests pass without errors

Test 4: Run Linter

npm run lint

✅ Success: No linting errors

Test 5: Test Transcription (Requires API Key)

Click "Choose Video File" or drag a video file (MP4, MOV, etc.)
Wait for video to load
Click "Start Transcription"
Verify:
- ✅ Processing status updates
- ✅ Transcript entries appear
- ✅ Speaker diarization works
- ✅ No API errors

Note: This test consumes API tokens and incurs small costs.

Troubleshooting

Issue 1: npm install fails with "EACCES" permission error

Solution (macOS/Linux):

sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules
npm install

Solution (Windows): Run Command Prompt as Administrator, then retry npm install.

Issue 2: "node-gyp" or "python" errors during npm install

Windows Solution:

npm install --global windows-build-tools

macOS Solution:

xcode-select --install

Linux Solution:

sudo apt-get install build-essential

Issue 3: Port 5173 already in use

Solution: Kill the process using the port or use a different port:

# Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:5173 | xargs kill -9

Or specify a different port:

npm run dev -- --port 3000

Issue 4: API Key not working

Possible causes:

API key is incorrect
Gemini API not enabled in Google Cloud
Billing not set up on Google Cloud

Solution:

Verify API key in .env file
Visit Google AI Studio
Regenerate API key
Ensure billing is enabled in Google Cloud Console

Issue 5: Electron build fails

Windows - Missing Visual Studio Build Tools:

npm install --global windows-build-tools

macOS - Code signing issues: Add to package.json → build section:

"mac": {
  "identity": null
}

Linux - Missing dependencies:

sudo apt-get install libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils libatspi2.0-0 libdrm2 libgbm1 libxcb-dri3-0

Issue 6: TypeScript errors during build

Solution:

# Clean build cache
rm -rf dist
rm -rf node_modules/.vite

# Rebuild
npm run build

Issue 7: Git hooks not running

Solution:

# Reinstall Husky
npm run prepare

# Check hook permissions (macOS/Linux)
chmod +x .husky/pre-commit
chmod +x .husky/commit-msg

Issue 8: Out of memory during build

Solution: Increase Node.js memory limit:

# Windows (PowerShell)
$env:NODE_OPTIONS="--max-old-space-size=4096"
npm run build

# macOS/Linux
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Next Steps

For Development

Read the README for detailed development guide
Explore the demo mode to understand features
Review code in src/ directory
Check manual.html for user documentation

For Contributing

Create a new branch: git checkout -b feature/your-feature-name
Make changes and commit: npm run commit
Push to GitHub: git push origin feature/your-feature-name
Create a Pull Request

For Building Releases

Update version in package.json

Build for all platforms:

npm run electron:build:win
npm run electron:build:mac
npm run electron:build:linux

Upload installers to GitHub Releases

Additional Resources

Documentation

User Manual - Complete user guide
Development Guide - Detailed development documentation
GitHub Repository - Source code

External Documentation

Support

GitHub Issues: Report bugs
Email: Contact developer at keven@example.com

Summary Checklist

Before you start development, ensure you have completed:

✅ Installed Node.js (v18+)
✅ Installed Git
✅ Installed a code editor (VS Code recommended)
✅ Cloned the repository from GitHub
✅ Ran npm install successfully
✅ Created .env file with Google Gemini API key
✅ Ran npm run dev and verified app loads
✅ Loaded demo transcript successfully
✅ Ran tests with npm test

Quick Reference Commands

# Clone repository
git clone https://github.com/KevenWMarkham/transcript-parser.git
cd transcript-parser

# Install dependencies
npm install

# Configure environment
# Create .env file and add: VITE_GEMINI_API_KEY=your_key

# Development
npm run dev                    # Start dev server (web)
npm run electron:dev           # Start Electron dev mode

# Build
npm run build                  # Production build (web)
npm run electron:build:win     # Build Windows installer
npm run electron:build:mac     # Build macOS app
npm run electron:build:linux   # Build Linux app

# Testing
npm test                       # Run unit tests
npm run test:watch             # Run tests in watch mode
npm run test:e2e               # Run E2E tests

# Code Quality
npm run lint                   # Check for linting errors
npm run lint:fix               # Auto-fix linting errors
npm run format                 # Format code with Prettier

# Git
npm run commit                 # Interactive commit (recommended)
git commit -m "type: message"  # Manual commit

Last Updated: December 19, 2024 • Version 1.0.0

FilesExpand file tree

installation-guide.md

Latest commit

History

installation-guide.md

File metadata and controls

Transcript Parser - Complete Installation Guide

Overview

Table of Contents

System Requirements

Minimum Requirements

Recommended

Install Prerequisites

Step 1: Install Node.js

Windows

macOS

Linux (Ubuntu/Debian)

Verify Node.js Installation

Step 2: Install Git

Windows

macOS

Linux (Ubuntu/Debian)

Verify Git Installation

Configure Git (First Time Setup)

Step 3: Install a Code Editor (Optional but Recommended)

Visual Studio Code (Recommended)

Alternative Editors

Step 4: Install Python (Windows Only - for native dependencies)

Windows

macOS/Linux

Clone the Repository

Step 1: Choose a Project Directory

Step 2: Open Terminal/Command Prompt

Step 3: Navigate to Your Project Directory

Step 4: Clone the Repository

Step 5: Navigate into the Project

Project Setup

Step 1: Install Project Dependencies

Step 2: Install Playwright Browsers (for End-to-End Testing)

Configure Environment

Step 1: Obtain Google Gemini API Key

Step 2: Create Environment File

Windows (Command Prompt)

Windows (PowerShell)

macOS/Linux

Step 3: Add API Key to .env File

Step 4: Verify .env File

Build the Application

Step 1: Build for Development (Quick Test)

Step 2: Build for Production

Step 3: Build Electron Application (Desktop App)

Windows

macOS

Linux

Run the Application

Option 1: Development Mode (Web Browser)

Option 2: Electron Development Mode (Desktop App)

Option 3: Production Build (Web)

Option 4: Installed Electron App

Verify Installation

Test 1: Check Development Server

Test 2: Load Demo Transcript

Test 3: Run Tests

Test 4: Run Linter

Test 5: Test Transcription (Requires API Key)

Troubleshooting

Issue 1: npm install fails with "EACCES" permission error

Issue 2: "node-gyp" or "python" errors during npm install

Issue 3: Port 5173 already in use

Issue 4: API Key not working

Issue 5: Electron build fails

Issue 6: TypeScript errors during build

Issue 7: Git hooks not running

Issue 8: Out of memory during build

Next Steps

For Development

For Contributing

For Building Releases

Additional Resources

Documentation