[Userscript] Open Framework JLPT, Joyo, and Frequency filters

:warning: This is a third-party script/app and is not created by the WaniKani team. By using this, you understand that it can stop working at any time or be discontinued indefinitely.

For users of Self-Study Quiz

This scripts adds filters that allow you to study kanji by JLPT level, Joyo grade, and and Frequency bracket.

For developers

This script adds, in addition to the above three filters, another three filters which just add data to the items in your request. Note: This script only adds info to kanji.

  • include_jlpt_data: Adds a field jlpt_level to each item that has an associated JLPT level. Possible values are 1-5.
  • include_joyo_data: Adds a field joyo_grade to each item that has an associated Joyo grade. Possible values are 1-6 and 9.
  • include_frequency_data: Adds the following fields to each item that has the associated data:
    • frequency one of the integers 500, 1000, 1500, 2000, 2500 indicating the frequency bracket of the kanji, where 500 means it’s one of the 500 most frequent kanji.
    • nhk_frequency a float between 0 and 1 indicating the relative frequency in NHK Web Easy online news articles.
    • news_frequency a float between 0 and 1 indicating the relative frequency various news articles.
    • aozora_frequency a float between 0 and 1 indicating the relative frequency in Aozora Bunko fiction/non-fiction books.
    • twitter_frequency a float between 0 and 1 indicating the relative frequency in twitter posts.
    • wikipedia_frequency a float between 0 and 1 indicating the relative frequency in wikipedia articles.

When using these filters that only add data you can set the filter value to anything, it doesn’t matter whether it’s true or false or anything else.

Available at

that place where you buy coffee filters


Slow down with the scripting. You’re putting the rest of us to shame.


I will have to lest I start failing some classes… I just have redo JLPT Percentages with these filters and lots of options… then I’ll be out of ideas

1 Like

Are you working on a specific script??? A contest is happening.

Yes. I made this to extend the script I already made for the contest

It’s bed time and your framework got me a great idea… Cant… Sleep… Must… Co…de


Hope I’m the first developer who used it? The new version of Advanced Context Sentence now uses your filters.

One thing I noticed is that you don’t have a way for us to check if the script is installed of not, so I had to @require it. but this is bad since you require Wanikani Open Framework to be installed and I don’t want my script to be only runable if a certain script is installed first. so now anyone who didn’t install Wanikani Open Framework will get your script dialog every time they refresh the page

I would force Wanikani Open Framework usage, but since there are features that can be done without it (highlighting and audio, in my case), then it’s kinda bad to do



1 Like

I see. I can remove the wkof check in the filter script.
I think requiring the filters is the best way though, to avoid having too many dependencies for users to download.

I’m using the filters too… So technically you’re not the only one :wink:



This was probably not necessary since it will be installed as long as the user has wkof (and you can just check whether they do), but I added a global variable to indicate whether the script is running.
window.jlpt_joyo_freq_filters contains a boolean

I removed the alert asking the user to install wkof. If they do not have wkof then the script just won’t run. Should still be fine for my script and it should be fine for anyone using it with the self study script.

@Kumirei @abdullahalt,
It’s important to consider startup sequence when checking if something is installed.
For example, if ScriptA requires ScriptB:

  • What happens if A runs before B?
  • What happens if B runs before A, but B isn’t done initializing yet?

wkof has a solution for that.

When a script is ready to provide services, it can set a global event flag:

// wkof.set_state(state_name, state_value);
wkof.set_state('ScriptA.status', 'ready');

When a script needs to wait for a service to become available:

// wkof.wait_state(state_name, state_value[, callback[, persistent]])
//    * If no callback, a Promise is returned
//    * If persistent==true, the callback will be called each time the state
//      changes to the desired value.
wkof.wait_state('ScriptA.status', 'ready', ready_callback);
1 Like

I see. That’s useful. Shouldn’t be necessary if the script is @require’d though, right?

True, but @require’ing a script has issues:

  • @require refers to a specific version, and won’t receive updates
  • What if two scripts @require different versions of the same add-on? One will overwrite the other, depending on the order in TamperMonkey (or whatever).

Got it.
I’ll update the script to use the flag tomorrow, if you’re ok with that @abdullahalt

This case never crossed my mind. In my current state, i think my script will break if wkof is ready but jlpt is not. Is there a way for @Kumirei to add his “ready” flag with wkof.ready? In this case i can just do wkof.readt(“Settings, Jlpt”) for example

Sure thing


is essentially equivalent to:

wkof.wait_state('wkof.' + module_name, 'ready');

because .ready() was originally designed just for wkof modules, so it prepends "wkof." as sort of a namespace.

However, as long as @Kumirei uses a personal namespace as a prefix, I have no problem with doing something like this:

wkof.set_state('wkof.Kumirei.ScriptName', 'ready');

… which would allow you to do this:

wkof.ready('ItemData, Menu, Settings, Kumirei.ScriptName').then(do_something);

Amazing, clean and simple. I didn’t have the chance before to say that but really your framework is super great and I appreciate it


For version 0.1.3, you added a flag to let us know your script is ready, but no flag for us to know when you’re ready to provide services. I think it’s better to follow @rfindley’s advice and go with wkof.set_state.

yeah, I made that update before he mentioned it and didn’t have time to do the set_state thing yesterday. I’ll get to it today.

1 Like

Script now sets a flag when all the filters have been registered.
I used wkof.Kumirei.JJFFilters (JLPT Joyo Frequency Filters).

1 Like