Jaffe-Lurie Transcribble

An offline user friendly transcription tool

• Uses various openai-whisper based models to transcribe audio or video files.
• Runs locally.
• Outputs into a clean .cha file by utterance.
• As always, TRUST NOTHING GENERATED BY AI, and always verify

REQUIREMENTS:

See the installation section for detailed step by step instructions.

1. Internet (for install and download of AI models to be run locally)
2. FFMPEG (should be available via environment PATH)
3. GIT (should be available via environment PATH)
4. PYTHON 3.11+ (should be available via environment PATH)
5. Huggingface key/account (for download of AI models to be run locally)
6. [Optional] CUDA (requires NVIDIA GPUs, for faster runtime)

Installation:

1. Internet

   • For installation of the transcriber
   • For the AI model download - on the first time you use a model

2. Python 3.11+:

   • Download and install python here: https://www.python.org/downloads/
   • Tested on 3.11, 3.12, and 3.13
   • If using the installer, use the following configuration options:
     • Click on Modify or Customize installation (whichever one you see)
     • Select Add python.exe to PATH (for ease of use)
     • Select pip (to install pip)
     • Select tcl/tk and IDLE (to install tkinter)
     • Select Add python to environment variables (might be on the second page)
     • Select Download debugging symbols (might be on the second page)
     • Reccomended to select Install Python for all users (might be on the second page)
   • You might need to restart your computer here if it prompts you for it
   • NOTE: If you already have python installed, make sure you have tkinter tcl/tk installed!
     • Check by running the command: python -m tkinter If a window pops up, you have it installed and can continue to the next requirement step!
     • To install:
       • MacOS:
         • Run the command: brew install python-tk
       • Windows:
         • Download the installer for the version of python you currently have and follow the installation configuration. python --version

3. GIT:

   • Check to see if you have git installed by running the command: git --version or python -c 'command="git"; import shutil; path = shutil.which(command); print(f"{command} installed @ {path}" if path else f"{command} is not installed or cannot be found!")'

     If you do have git, you can skip to the next requirement.

   • See here for detailed guide on installing git or skip to the section for your OS: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git#main

   • MacOS:

     • Install the Xcode Command Line Tools. On Mavericks (10.9) or above, start by checking to see if you have it installed already by running the following command: git --version If you don’t have it installed already, it should prompt you to install it. If it does not, see the detailed guide on installing git above.

   • Windows:

     • Automatic install with command line: winget install -e --id Git.Git
     • Or manual install git for windows from the offical git website: https://git-scm.com/downloads/win
       • Click on the first install link. It should look like the following

         Click here to download the latest (##.##.##) x64 version of Git for Windows.

       • When installing, use the default configuration for all steps except:
         • Choosing the default editor used by Git: Select an application that you already have for ease of use, recomended to select "Use Notepad as Git's default editor".
         • Configure line ending conversions: Choose "checkout as-is, commit Unix Style line endings".
         • Configure extra options: Select "Enable symbolic links" - checking this here might allow you to skip one of the install steps later on.

   • Linux:

     • sudo apt install git-all

4. FFMPEG:

   • Check to see if you have FFMPEG installed by running the command: ffmpeg -version or python -c 'command="ffmpeg"; import shutil; path = shutil.which(command); print(f"{command} installed @ {path}" if path else f"{command} is not installed or cannot be found!")'
   • MacOS: install ffmpeg to be made available by the command line
     • brew install ffmpeg
   • Windows:
     • Automatic install with command line: winget install ffmpeg
     • OR manual install here instant download link to zip file or follow the instructions on the offical ffmpeg webiste here https://ffmpeg.org/download.html.
       • If you installed manually, follow these steps:
         • Unzip (or move the unzipped files) to C:/Program Files/ffmpeg The results should look like the following:
         • Add the C:/Program Files/ffmpeg/bin (or wherever you downloaded it to + /bin) to your system environment PATH variable
           • in windows bar search, type "env" and follow the arrows in the image below
           • when you click "new" enter C:\Program Files\ffmpeg\bin. DO NOT EDIT ANY OTHER LINE THAT IS ALREADY THERE!

5. CUDA

   • If you can, use CUDA to increase performance when running the AI.
   • NOTE: You will need a NVIDIA GPU for this.
   • Install CUDA
   • If this sounds like gibberish to you, it is safe to skip this step. Your AI models will run off of your CPU.

6. Python's tkinter needs to be installed

   • If you installed python with the installer and selected the tk/tcl and IDLE options, you should have this step completed already.
   • MacOS:
     • Run the command: brew install python-tk
   • Windows:
     • See the install Python 3.11+ step and download the installer for the version of python you currently have. python --version

7. If on windows and did not select the "enable symbolic links" option when installing GIT, do the following:

   • Enable symbolic links on your machine.
   • Open the Local group policy editor and add your account user to the following:

8. The Transcriber: Now that you have all of the requirements installed we will install the Transcriber from git

   1. Open your choice terminal window

      • Reccomended to use Powershell or git bash on windows, use default terminal on Mac/linux

   2. use "cd" to change directory to where you want to install the transcriber example: to your Documents folder: cd ~/Documents

   3. Clone the Transcribble repo: git clone https://github.com/Noah-Jaffe/Transcribble.git NOTE: If you get the error: fatal: destination path 'Transcribble' already exists and is not an empty directory., you will need to either delete the existing Transcribble folder, or rename the existing one. Or install to a custom directory by replacing NEW_FOLDER_NAME in the following command: git clone https://github.com/Noah-Jaffe/Transcribble.git NEW_FOLDER_NAME.

   4. Enter the Transcribble directory in the terminal cd Transcribble or cd ~/Documents/Transcribble

   5. Setup a python virtual environment if you want, skip this step if you are unfamiliar. python -m venv .venv

      • Start/Activate your virtual python environment with
        • Windows
          • Powershell ./.venv/Scripts/activate
          • git bash source ./.venv/Scripts/activate
        • MacOS/Linux
          • source ./.venv/bin/activate

   6. Install python packages with the command: pip install -r requirements.txt

      • If the pip install fails try installing each package one at a time, by line as it is written in the requirements.txt file.
      • If that fails, report the issue to the maintainer or your point of contact
      • The only requirements not in the txt files are torch torchaudio and torchvision (continue reading...)

   7. Install requirements not in the requirements.txt

      1. If you are using CUDA:
         • You may need to pip uninstall torch torchaudio torchvision before doing this next step.
         • See here to reinstall torch torchaudio and torchvision with your appropriate build: https://pytorch.org/get-started/locally/
           • Example for if you have a CUDA compatible device for 12.6 you would run: pip install torch torchvision torchaudio --no-cache -U --index-url https://download.pytorch.org/whl/cu126
      2. Otherwise if you dont have a CUDA compatible GPU or dont know what that means then run the next line:
         • pip install torch torchaudio torchvision

   8. Put your Huggingface token in a file named .hftoken.

      • .hftoken only, .hftoken.txt will not work
      • Generating the token:
        • You may need to create a huggingface account, you can skip all the optional steps except for verifying your email.
        • You can name the token anything on the setup page, just save the resulting token to a file called .hftoken to your machine.
        • When asked to setup the token permissions, please note that the token does not need any special permissions and you can deselect all of the options.

   9. If you want to make a one click startup script, you could do so now.

      • Example for windows: Save anywhere as "Transcribe.ps1"

        cd ~/Documents/Transcribble
        # if you used a virtual environment uncomment the next line (remove the #)
        #./venv/Scripts/activate
        python main.py

      • Example for Mac/Linux Save anywhere as "Transcribe.sh"

        #!/bin/bash
        cd ~/Documents/Transcribble
        # if you used a virtual environment uncomment the next line (remove the #)
        # source .venv/bin/activate
        python main.py
        

        You may need to run chmod +x Transcriber.sh on the new .sh file to give it permissions to execute
      • NOTE: You might need to do some additional research for how to do this properly for your machine.

9. Continue to the using Transcribble step.

---

Using Transcribble

1. Start the application
   • If using a virtual environment start/activate that now. See here
   • Run the program with python ./main.py
   • Or use your one click script file.
2. Select files (button) to be transcribed.
   • Set the number of speakers in the number box.
   • [Optional] Set the language (if not english).
3. Select AI model to use from the drop down.
   • Hover over the drop down to see some selection guidance. Choose one that your device can handle.
   • Read more about the models here.
4. Start transcript (button).
5. Wait for final results popup to appear. Your transcribed files should automatically open as they are completed.
6. Review resulting transcripts.

---

Citation

Please see the CITATION file for citing this work.

Jaffe, N., & Lurie, S. (2025). Jaffe-Lurie Transcribble [Computer software]. GitHub. https://github.com/Noah-Jaffe/Transcribble

---

Frequently asked questions:

How to update my Transcribble app?

If you followed the instructions on this readme file, or installed this repo with git:

1. Enter the Transcribble directory in the terminal cd Transcribble or cd ~/Documents/Transcribble
2. Update to the latest version with the following commands: git pull
3. Re-install the latest requirements
   • If using a virtual environment start/activate that now if it is not already activated. See here
   • reinstall pip requirements

• [Optional] Check the readme, changelog, or release notes to see if there is anything else you need to change.

Help, some error occured that is not covered elsewhere!

• Send as much relevant info to the maintainer such as:
  • the terminal logs
  • screenshots of what is wrong
  • explinations for what was expected to happen
  • .cha file (you can remove sensitive information from the transcripts, but leave the @debug lines)

How do I get rid of these ugly @debug lines in my .cha file?

De-select the Debug checkbox before clicking the start transcribe button.

Where is the core logic for the AI?

See function transcribe_file in transcribe_proc.py.

Yall got some Morphosyntax?

In function transcribe_file in transcribe_proc.py: Uncomment the line inside the pipeline_activity variable array:

        # morphosyntax,

so that it looks like

        morphosyntax,

How do I use this in more fine detail?

See the __doc__ in the transcribe_proc.py file.

I want to split a file into files of smaller (but relatively equal length) chunks!

Run python splitfile.py

1. Select the files to be split
2. Input the number of seperations and the seconds of overlap between each split file
3. Click split file
4. Find the output files next to the input files as <file_name>.#.<ext>
   • e.g. Input file myfile.mp3 split into 2 files will result in files: myfile.1.mp3 myfile.2.mp3 (the original file will not be changed or moved)

Help, I got a TypeError: ... not supported between instances of 'NoneType' and 'float'!

If you run into the following errors specifically in the Whisper (Step 1), know that this is an error of the AI and may not entirely be in our control.

TypeError: '<=' not supported between instances of 'NoneType' and 'float'

TypeError: '>' not supported between instances of 'NoneType' and 'float'

One patch for this is to use python package transformers==4.38.2.

To attempt patch #1:

• If using a virtual environment start/activate that now. See here
• Run pip install transformers==4.38.2

If you are already using this version of transformers, I'm sorry but the only known workaround is to split up the original file into smaller segments, and then run the smaller segments through the transcriber again. Eventually you may hit a small section of the original audio file that crashes constantly, for that you will have to transcribe by hand.

Note that this issue should be fixed as of Transcribble release 1.1.1!

---

Backlog ideas:

• Advanced/Runtime configuration of AI parameters?
  • multiple times or using different models?
  • note that you can do this by scripting something to use the transcribe_proc.py. See the file for how to pass values.
• Bundle into single executable to be more user friendly?
• Select subframe of time to transcribe from?
• Better error handling
• Checkboxes for pipeline steps?
• Research Inter-sentential code-switching
• Custom setup for auto run script on output .cha file?
• Remove reliance on batchalign?