Read Time Counter JS

Read Time Counter JS is a robust, highly configurable library that estimates reading time for English, CJK (Chinese, Korean, Japanese), and Latin-based languages by analyzing words, characters, and images.

Features

• Accurate word counting for English and Latin-based languages.
• Character counting for CJK (Chinese, Korean, Japanese) languages.
• Image viewing time calculation.
• Customizable reading speeds and output targets.
• Lightweight and easy to integrate.
• TypeScript Support (New!)
• NPM Package (New!)

Installation

1. npm

npm install readtimecounter

import { analyzeText, calculateReadingTime } from 'readtimecounter';

const text = "Hello world";
const stats = analyzeText(text);
const time = calculateReadingTime({ ...stats, imgCount: 0 });
console.log(time); // Minutes

2. Browser Script (CDN)

You can look up the latest version on jsDelivr or unpkg. Using the GitHub source (which corresponds to readtime.js in the root of this repo):

<script defer src="https://cdn.jsdelivr.net/gh/SPACESODA/readtimecounter@latest/readtime.min.js"></script>

Or download the js file and include it locally.

3. Local Development (Building from Source)

If you want to contribute or modify the script:

1. Clone the repository

   git clone https://github.com/SPACESODA/readtimecounter.git
   cd readtimecounter

2. Install Dependencies

   npm install

3. Run Development Server This will start a local server and listen for changes. index.html uses the locally generated script.

   npm run dev

4. Run Tests Verify that the core logic (word counting and time calculations) is correct.

   npm run test

5. Build Generate the production files.

   npm run build

   • readtime.js: Generated in the root folder. This is the un-minified browser script (with banner) for GitHub usage.
   • dist/: Contains the library files (index.mjs, index.cjs) and TypeScript definitions for NPM.

Usage (Browser Global)

1. Define the Content Area

Wrap your article or content in an element with the ID readtimearea.

<article id="readtimearea">
  <!-- Your content goes here -->
</article>

Note: Only one readtimearea is supported per page.

2. Display the Output

Add elements with specific IDs where you want the statistics to appear.

| ID | Description | | :------------ | :--------------------------------------------------- | | readtime | Estimated reading time in minutes. | | wordCount | Total word count (English/Latin). | | ckjCount | Total CJK character count. | | imgCount | Total image count. | | hybridCount | A combined summary of words, characters, and images. |

Example:

<p>Estimated reading time: <span id="readtime"></span> minutes</p>

<div class="stats">
  <span id="wordCount"></span> words | 
  <span id="ckjCount"></span> characters | 
  <span id="imgCount"></span> images
</div>

<!-- Or use the summary -->
<p><span id="hybridCount"></span></p>

Configuration

You can customize the reading speed and other settings by defining window.readingTimeSettings before the script loads.

<script>
  window.readingTimeSettings = {
    engSpeed: 275,         // English words per minute
    charSpeed: 500,        // CJK characters per minute
    imgSpeed: 12,          // Seconds per image
    timeFormat: "decimal", // "decimal" or "integer"
    // Custom Selectors (optional)
    readTimeTarget: "readtime",
    wordCountTarget: "wordCount",
    ckjCountTarget: "ckjCount",
    imgCountTarget: "imgCount",
    hybridCountTarget: "hybridCount",
    readTimeArea: "readtimearea"
  };
</script>
<script defer src="https://cdn.jsdelivr.net/gh/SPACESODA/readtimecounter@latest/readtime.min.js"></script>

Default Settings

| Option | Type | Default | Description | | :----------- | :----- | :---------- | :----------------------------------------------- | | engSpeed | Number | 275 | Reading speed for English words (WPM). | | charSpeed | Number | 500 | Reading speed for CJK characters (CPM). | | imgSpeed | Number | 12 | Time allocated for viewing each image (seconds). | | timeFormat | String | "decimal" | Output format: "decimal" or "integer". |

Contributing

Please feel free to comment, contribute, and make the code better!

Run npm test to verify changes.

References

• English Alphabet
• CJK Characters
• Universal Character Set