Timeframes

The global timeframe namespace exposes normalized information about the script/chart timeframe.

These helpers use MMT timeframe semantics:

• bare numeric arguments mean seconds
• timeframe strings use MMT units like 10s, 30m, 4h, 1D, 2W, 3M, 1Y
• timeframe.period returns normalized MMT strings

Fields

Examples:

• 60 seconds chart -> period === "1m", multiplier === 1
• 14400 seconds chart -> period === "4h", multiplier === 4
• 86400 seconds chart -> period === "1D", multiplier === 1

timeframe.change

timeframe.change(timeframe) -> boolean

Returns true on the first chart bar of a new requested timeframe period.

Arguments:

• timeframe: MMT timeframe string or positive integer seconds

//@version=2
indicator("New Day Started", true)

function onBar(index) {
  const isNewDay = timeframe.change("1D")
  if (isNewDay) {
    bg("new-day", {
      color: color.transp(color.green, 80),
    })
  }
}

timeframe.change() uses the primary/chart clock and is not available inside subscription.calc(...).

timeframe.inSeconds

timeframe.inSeconds(timeframe?) -> number

Converts an MMT timeframe string into seconds. When omitted, it returns the current script/chart timeframe in seconds.

Arguments:

• timeframe: optional MMT timeframe string or positive integer seconds

//@version=2
indicator("Timeframe Seconds", false)
const tf = input.timeframe("Higher Timeframe", "4h", { key: "htf" })

function onBar(index) {
  plot("chart_tf", timeframe.inSeconds())
  plot("input_tf", timeframe.inSeconds(tf))
}

Because input.timeframe() already returns seconds, its result can be passed directly to timeframe.change() and timeframe.inSeconds().

timeframe.fromSeconds

timeframe.fromSeconds(timeframe?) -> string

Converts a seconds value into the canonical MMT timeframe string. When omitted, it returns the current script/chart timeframe string.

This follows the same normalized formatting as pkg/timeframe.FromSecondsNormalized(...).String(), so values like 60, 3600, and 86400 become 1m, 1h, and 1D.

Arguments:

• timeframe: optional MMT timeframe string or positive integer seconds

//@version=2
indicator("Timeframe String", false)
const tf = input.timeframe("Higher Timeframe", "4h", { key: "htf" })

function onBar(index) {
  log("chart_tf=" + timeframe.fromSeconds())
  log("input_tf=" + timeframe.fromSeconds(tf))
  log("odd_tf=" + timeframe.fromSeconds(90))
}

When a string is passed, timeframe.fromSeconds() returns its canonical MMT representation. For example, "1d" becomes "1D" and "60" becomes "60s".