Estimated Reading Time for Blog Posts, Articles, etc.

A simple implementation of Medium's Read Time calculation.

Examples (TL;DR)

import net.thauvin.erik.readingtime.ReadingTime

// ...

val rt = ReadingTime(htmlText)
println(rt.calcEstimatedReadTime()) // e.g. 2 min read

• View bld or Gradle Examples

To get the estimated reading time in seconds use the calcReadingTimeInSec() function.

bld

To use with bld, include the following dependency in your build file:

repositories = List.of(MAVEN_CENTRAL, CENTRAL_SNAPSHOTS);

scope(compile)
    .include(dependency("net.thauvin.erik:readingtime:1.0.0-SNAPSHOT"));

Be sure to use the bld Kotlin extension in your project.

Gradle, Maven, etc.

To use with Gradle, include the following dependency in your build file:

repositories {
    maven {
        name = 'Central Portal Snapshots'
        url = 'https://central.sonatype.com/repository/maven-snapshots/'
    }
    mavenCentral()
}

dependencies {
    implementation("net.thauvin.erik:readingtime:1.0.0-SNAPSHOT")
}

Instructions for using with Maven, Ivy, etc. can be found on Maven Central.

Properties

The following properties are available:

ReadingTime(
    text,
    wpm = 275,
    suffix = "min read",
    pluralSuffix = "min read",
    excludeImages = false, 
    extraSeconds = 0,
    roundingMode = RoundingMode.HALF_EVEN
)

Property	Description
text	The text to be evaluated. (Required)
wpm	The words per minute reading average.
suffix	The value to be appended to the reading time.
pluralSuffix	The value to be appended if the reading time is more than 1 minute.
excludeImages	Images are excluded from the reading time when set.
extraSeconds	Additional seconds to be added to the total reading time.
roundingMode	The rounding mode to apply.

DSL

A Kotlin DSL is also available:

val est = readingTimeEstimator {
    text("This is a DSL example.")
    wpm(220)
    suffix("min")
    pluralSuffix("mins")
    excludeImages(true)estimator
    extraSeconds(5)
}

val readTime = est.readingTime() // e.g. 3 mins

Functions

A couple of useful static functions are also available:

ReadingTime.countWords(htmlText) // Returns the count of words. (HTML stripped)
ReadingTime.countImages(htmlText) // Returns the count of images. (HTML img tags)

None of the attributes are required.

Java

An Java API surface is also available:

var est = ReadingTimeEstimator.create(
        ReadingTimeConfig.Builder(htmlTxt)
                .wpm(220)
                .suffix("min")
                .pluralSuffix("mins")
                .excludeImages(true)
                .extraSeconds(5)
                .build()
);

var readTime = est.readingTime(); // e.g. 3 mins
var seconds = est.readingTimeInSeconds(); 

var est = ReadingTimeEstimator.create(text, "min", "mins");
var est = estimator.readingTime(); // e.g. 3 mins

or using a configuration builder:

var cfg = new ReadingTimeConfig.Builder(htmlText)
        .wpm(250)
        .suffix("min")
        .pluralSuffix("mins")
        .excludeImages(true)
        .extraSeconds(5)
        .roundingMode(RoundingMode.HALF_EVEN)
        .build();

var est = ReadingTimeEstimator.fromConfig(cfg);

var readTime = est.readingTime();
var minutes = est.readingTimeInMinutes();

JSP

A JSP tag is also available for easy incorporation into web applications:

<%@taglib uri="https://erik.thauvin.net/taglibs/readingtime" prefix="rt"%>
<rt:readingtime
    wpm="275"
    prefix="min read"
    pluralPrefix="min read"
    excludeImages="false"
    extra="0">some_text</t:readingtime>

Contributing

See CONTIBUTING.md for information about contributing to this project.

More…

If all else fails, there's always more Documentation.